Creating supertasks in DITA

1. Creating supertasks in DITA Presented to the Silicon Valley DITA Interest Group August 9, 2006 Megan Bock

2. Discussion topics • What is a supertask? • How do you create a supertask? • How do you add related content without interrupting the sequence? • What can you do to handle difficult supertasks?

3. Supertask • A supertask is a series of tasks that the reader should perform in a specific order. • In DITA, a supertask provides automatic linking: • From the supertask to the step tasks • From each step task to the supertask • From each step task to the preceding and following step tasks • A supertask can be a step task in a larger supertask.

4. Creating a supertask • Create topics using the DITA task topic type: • Create a container topic for the supertask. Provide prerequisites, contextual information, and so forth. • Create a topic for each step task. • Add topic references in the DITA map: • Add a topicref element for the supertask container topic and set the collection-type attribute to sequence. • Insert the step topics. Nest them, in order, inside the container topic’s topicref element.

5. A supertask in the DITA map A step topic in a supertask can be the container for another supertask.

6. The supertask container topic: DITA source and XHTML output

7. Hierarchical links in output • XHTML: Hierarchical links are created in the supertask container at build time. • Numbered task links in the parent. • Parent topic links in each child. • Sequence links in each child. • PDF: No hierarchical links are created.

8. The short description in hierarchical links • The title and short description become the ordered list items. • HTML output for task 1: <li class="olchildlink"><a href="jack_assembling.html">Assembling the jack</a><br /> Your jack might require assembly before you can use it to lift your vehicle.</li>

9. Adding related content without interrupting the sequence • If you deliver PDF or books, insert a topicref element where you want to place the related content. • Use a relationship table to link to the related content from the supertask container and any of the step tasks. • If the related content is a child of the supertask container, turn off linking for the related content topic or topics.

10. Inserting and linking a concept topic ← Use linking=“none” to keep the concept out of the task sequence. ← Use toc=“no” to keep the concept topic out of the navigation. Use a relationship table to control all linking to the concept. → ↓Use index entries normally.

11. Using a relationship table to add a concept • Relationship tables define links outside the topic hierarchy. • Relationship tables can be designed in different ways. Basic designs include: • Source and target columns (shown) • Topic type columns • Single column

12. The short description in related links • In XHTML output, the content of the shortdesc element becomes the title attribute on the related links, parent link, and sequence links. Sample output: <a href="jack.html" title="A jack is a device that you can use to lift a vehicle.">Jack</a> • In PDF output, the content of the shortdesc element is positioned below the related link.

13. Difficult supertasks • A task in the sequence doesn’t have a topic or is not a local topic • Sequences intersect, fork, or run parallel • Intersecting: Two sequences use the same topic • Forking: The sequence splits and does not rejoin • Parallel: The sequence splits and then rejoins

14. Solutions for difficult supertasks • Simulate a supertask • Slightly different output, especially in PDF • More difficult to maintain • Good for: step that is not a topic or a local topic • Use the copy-to attribute on a topicref element • More output files and longer PDFs • Duplicates in the index and search results • Good for: intersecting tasks • Insert a transition topic • Time-consuming to create and maintain • Good for: forking tasks • Create shell topics • Time-consuming to create and maintain • Good for: parallel tasks, intersecting tasks

15. Tagging example for a simulated supertask To simulate a supertask: • Make the short descriptions in the step task topics reusable. • Build the task as inline links in the steps of the supertask. • Break the generated linking in the map. • Rebuild the linking with a relationship table.

16. Make the short descriptions reusable Insert a ph element around the text of the short description. (You can’t reference a short description as the conref target in a step.)

17. Build the tasks as steps • Create a step for each task topic. • Insert an xref element in the cmd element. • Insert an info element to hold the short description content. • Insert a ph element with a conref attribute targeting the topic’s short description.

18. Break the generated linking in the map • Nest the step task topics inside the supertask container topic. • Do not assign a collection-type attribute on the topicref element for the supertask container topic. • Turn off linking to each of the step task topics in the supertask.

19. Rebuild the linking with a relationship table • Duplicate the supertask structure in a cell in a relationship table. • For the supertask container topic, set the collection-type attribute to sequence and the linking attribute to target-only. • For each of the step task topics, set the linking attribute to normal. (The attribute is inherited from the supertask container, so you have to turn linking back on.)

20. XHTML output comparison

21. PDF output comparison