Task Modeler Workflow, Tips, and Techniques

Mark E. Wallis, IBM Internet Security Systems

Overall Sequence
In Task Modeler
1. Set up your workspace (once only).
2. Create a new project (one for each ditamap).
3. Start a new ditamap.
4. Set up views.
5. Create topics.
6. Create parent-child relationships between topics.
7. Generate stub files.
8. Create a relationship table for related links.
9. Save your ditamap.

In your DITA-compliant editor

10. Open your DITA map.
11. Edit topics to add content and metadata.
12. Generate a CHM file using Apache Ant.

Later
• Use Task Modeler to edit structure (add/delete/move topics) and to edit the
relationship table.
• Use DITA-compliant editor to edit content and add metadata.
• Use DITA-compliant editor to create combination topics.
• Use DITA-compliant editor to create master ditamaps of other ditamaps.

Task Modeler
Create a new workspace and project in Task Modeler
1. Use Windows Explorer to create a workspace folder (directory) where your
content will live.
2. Open Task Modeler.
3. Click File > New > Project.
4. Click General > Project and click Next.
5. Type a project name for your project.
6. Select the workspace folder you created in step 1 and click Next.
7. Click Finish.

DocTrain West Vancouver May, 2008

Start a new DITA map in Task Modeler
1. Click File > New > Other > Task Modeling > DITA map and click Next.
2. Select the project folder you defined earlier.
3. Give the ditamap a prefixed name corresponding to your project and click
Next.
4. Clear the selections to use a template and import sample files and click
Next.
5. Accept all defaults on the DITA map page by clicking Finish.

Set up views in Task Modeler

1. Click Window > Open Perspective > Other > Dita Modeling and click
OK.
2. If they are not already showing, click Window > Show View > Other >
Dita and select the following:
• DITA Topic File Manager
• Relationship Table Editor
• Outline
• Navigator
3. Click View > View As > Hierarchical Diagram.
4. Turn off property visualization for all but Labels. (Click on Symbols and
Network and select Hide Visualization for each.

Create topics in Task Modeler

1. Select the node type in Task Modeler.
2. Create a node for each topic of the correct type (topichead, concept, task,
reference).
3. Build relationships between topics as needed.
4. Set properties for topics as needed.

Generate stub files in Task Modeler

1. Click DITA Topic File Manager tab.

2. Click the Generate Stub Files icon.

3. For the condition If the map topic contains no topic reference, then select
Generate Stub and Add Reference to Model and click Next.
4. Designate prefixes similar to the following and click Next.
Task file prefix: tasks\ditamap_prefix_
Concept file prefix: concepts\ ditamap_prefix_
Reference file prefix references\ ditamap_prefix_

5. Select Prompt before overwriting each file and click Next.

6. Review selections and click Finish.

* Remember that DITA is WYSIOO (What You See Is One Option)

DocTrain West Vancouver May, 2008

Create a relationship table for related topics in Task Modeler
1. Click the Relationship Table Editor tab.

2. Click the New Relationship Table icon.

3. Select Custom relationship table and then click Next.
4. Name the table Related Topics and click Finish.
5. Define topic relationships as needed.

Save your ditamap in Task Modeler

Generate a CHM file

1. Open your ditamap in your DITA-compliant editor.
2. Specifics for generating your CHM/Help file vary from editor to editor.

Tips and Techniques

• Define a single workspace only once for all your project files. Don’t create
projects or directories outside the workspace; it confuses Task Modeler.
• Close the ditamap in your DITA-compliant editor before making changes and
saving the ditamap in Task Modeler.
• Define each task support cluster (or equivalent) as a stand-alone project.
Each project corresponds to a single ditamap.
• Use filename prefixes for each file in a task support cluster using the file-
stubbing mechanism in Task Modeler. Also, use the same filename prefix
(such as m_dhcp_) for the ditamap itself. This keeps related files clustered
together—helpful when doing combined builds of multiple ditamaps.
• Use your DITA-compliant editor to edit content, create combination topics,
and create and manage master ditamaps that contain other ditamaps.
• When doing large builds, open the Windows Task Manager – Performance
Tab and keep an eye on CPU usage to make sure that the Apache Ant
compiler hasn’t died.
• Consider using a batch file (build.bat) like the following to copy content
from different writers into a single structure to do combined builds:
Set dirname=C:\Tempest_Help_Build\
xcopy *.ditamap %dirname% /V
xcopy concepts\*.dita %dirname%\concepts /V
xcopy tasks\*.dita %dirname%\tasks /V
xcopy references\*.dita %dirname%\references /V
To customize this for your project, modify the dirname variable to point to
the directory where you want to perform the build. Then place a copy of the
batch file in the directory of each topic cluster whose contents you want to
include. The easiest way to do this is to:
1. Copy the batch file and Ctrl-V paste it into a topic cluster
2. Double click it to run it (xcopy copies the files; /V verifies the copy)
3. Move to the next cluster and repeat
When you're done, you should have copies of all your material in the
destination (dirname) folders. Prepare a ditamap that calls all the relative
ditamaps and you're good to go.

DocTrain West Vancouver May, 2008