SVDIG Silicon Valley DITA Interest Group

8Sep/100

Meeting: Writing Effective Task Topics in DITA

Another great presentation by Michelle Carey and Shannon Rouiller (Technical Editors and Architects at IBM)! They covered the fundamentals of creating a DITA task topic as well as some of the more controversial and confusing issues that writers run into when creating tasks.

DITATaskTopics_090310SR.ppt


Notes from Tom Idleman (Thanks Tom!)

  • Combine small tasks, such as “Click OK”, with more significant tasks in one step.
  • Beware procedures that simply list imperative steps to interact with the UI without setting context or talking about why the user is performing the steps: “1. Click A. 2. Click B. 3. Click C…”
  • 9 steps, maximum, per task topic.
  • Only describe one way to do something.
  • Tag optional steps with the attribute importance set to optional.
    Note that IBM output generates an “Optional” label for steps tagged with importance = optional. (The label is not generated with a pre DITA-OT 1.5 PDF processor, a known issue with previous versions of the standard PDF processor.)
  • Instead of tagging something like “The blah window opens” as a <stepresult> of a step, use the information to set the context of the following step: “In the blah window, do thus and so.”
  • Use <choices> when a user has several choices in a step that can be explained in a short phrase. Use <choicetable> when a user has a combination of options, such as “In Windows, do this. In Linux, do that.”
  • IBM uses standard headings in task topics for the various parts of the task topic as follows:
    • Before you begin (Prerequisite)
    • About this task (Context)
    • Procedure (Steps)
    • Example (Example)
      Or if a <title> element is used in the tag, the text Example is overridden by the text of the <title>
    • Results (Result)
    • What to do next (Postrequisite)
  • IBM uses inline icons: “Click the (graphic of icon) icon.”
  • IBM uses gerunds to start task topic titles: “Medicating Your Cat”
  • IBM tags command names with <cmdname> when talking about the command and <userinput> when the user has to type the command name at a command line.
  • To construct a supertask, or in other words, a task that consists of many subtasks, IBM uses the following strategy in a DITA map:
    • A concept topic <topicref> that points to a concept that talks about the overall supertask.
    • An attribute setting of collection = sequence for the concept topic <topicref>
    • Embedded <topicref>s that point to the tasks that make up the supertask within the concept topic <topicref>.
    • The result is a concept topic with numbered links to the tasks that make up the supertask that looks like the following:
      “Emergency Diving a Submarine
      When your boat is spotted, submerging quickly is essential. The emergency-dive process is both complex and unforgiving. The individual tasks must be performed in the proper order and in a timely manner:

      1. 1) Clearing the Bridge
        The first step of an emergency dive is to get all personnel off the bridge of the submarine and safely into the boat. Typically, the OOD (Officer of the Deck) yells "Clear the Bridge" and sounds two bells to signify an imminent dive.
      2. 2) Closing the Hatches
        Before a submarine can dive, all external hatches need to be closed. Typically, only the conning tower hatch will be open, but more might be open depending on recent activity on the boat.
      3. 3) Stopping the Engines
        Submarine diesel engines require air intake to function. To prevent possible damage to the engines, stop them before closing the main induction.
        …”
  • To set prerequisite tasks, IBM sets the importance attribute to required for prerequisite tasks. This automatically creates a link in the prerequisite section of subsequent sibling task topics to the topic that’s topicref is set to importance = required.
    Note that this doesn’t work for our standard output. It’s currently unknown whether our changes to the OOB OTK functionality is short circuiting this behavior or if IBM has added this to their output.
Tagged as: No Comments
2Sep/100

Release 6.0 of DITAinformationcenter (a free DITA resource)

Release 6 of DITAinformationcenter was published today.

This version of our free DITA information and modeling resource supports DITA Open Toolkit 1.5.1 (final build) and the DITA 1.2 language standard (still to be approved).

New features include:

  • We have eliminated the code distribution. We recommend that you install the DITA Open Toolkit instead.
  • We have added topics on how we automated the creation of DITA files to document WSDLs (web services) using a Python script.
  • We have added topics on using Python code to do machine translation using Google Translate and Microsoft Translator (Bing).
  • We have added information on using Simplified English to improve the quality of translated content.
  • We are providing sample translations in Spanish and German of the garage and grocery shopping samples done using Google Translate and Microsoft Translator.

You can download the DITAinformationcenter from either vrcommunications.com resources page or xmldocs.info, which has been converted to a WordPress site.

-Anna and Dick

Filed under: DITA Tools No Comments