Thinking and Writing in DITA: Converting Legacy Content to DITA, Part 4

Old Fashioned Typist - DITA
Thinking and Writing in DITA, Part 4

This is a the fourth in a series of pieces devoted to “Thinking in DITA” aimed at providing technical writers just starting out with DITA the thought processes behind writing technical documents in DITA. Whereas most DITA tutorials focus on the mechanics of writing – such as DITA’s tag set – this series examines what goes into writing and thinking effectively in DITA first.

Re-writing Legacy Content as a Task Topic
The previous article looked at how to convert the “Introduction” section from the original Radio Shack TRS-80 Expansion Interface Operator’s Manual, (courtesy of Project Gutenberg) into a concept topic. In this article, I look at how to convert the following “Power Supplies and PCB Housing” section into two, separate task topics.

One Legacy Section Does Not Necessarily Equal One Topic
A best practice when it comes to writing in DITA is to stick to the principle of “one idea = one topic”. Having said that, read over the following section from the original manual:

Power Supplies and PCB Housing

Remove the Power Supply Door (top right side). First connect one DC power cord (DIN connector) to the Power connector on the PCB. Now install the two DC Power Supplies as illustrated. Route the remaining cords out the rear of the case. Be sure the power cords are seated in the door cutouts before replacing the Door.

To gain access to the future expansion PCB Housing, remove the Expansion Door from the top left side of the module.

NOTE: INSTALL EXPANSION INTERFACE DC POWER SUPPLY FIRST.

The term “port” as used in this manual refers to the openings into which the Cable connectors are inserted to provide an interconnection between the TRS-80 and the Expansion Interface modules.

The ports, with the exception of the Expansion Interface port, are also covered by removable Doors. To remove these Doors, press on the right side of the Door and it will pivot slightly. Grasp the left side of the Door and pull out.

While the text is a bit muddled, I read at least two separate procedures here: one for connecting the power supplies to the TRS-80 Expansion Interface, and the other on how to access its ports. Since we have two procedures, in DITA they equate to two separate task topics. This is in keeping with the idea that “one idea = one topic”, so “one procedure = one task”.

A good task topic focuses on the goals of the user, and does not simply describe the features or functions of the product – which the original manual arguably does.

So why would the user want to remove the power supply doors on the TRS-80 Expansion Interface? A: In order to plug it in and ultimately to power on the unit. What is so important about the port doors on the TRS-80 Expansion Interface? A: It is the way to connect other peripheral devices to the TRS-80 Expansion Interface. So while this section in the original manuals talks a lot about “doors” on the device, it’s a roundabout way of telling the user how and where to plug in power and attach peripheral devices to it.

The two names I am giving to these separate tasks are: “Setting Up the Power Supplies for the TRS-80’s Expansion Interface” and “Accessing the Ports on the TRS-80’s Expansion Interface” .

Providing Context for Tasks
One of the chief recommendations when writing DITA tasks is to provide same background for it, explaining some context and explaining why the following procedure is important, or where or when it ought to be done. Always focus on the user’s goals, not on the features of the product—as a colleague of mine used to say “they’ve already bought the product, now just tell them how to use it”.

Here’s my stab at providing some context for the first task (“Setting Up the Power Supplies for the TRS-80’s Expansion Interface”):

Two separate power supplies need to be installed within the housing of the TRS-80 Expansion Interface. One provides power to the TRS-80 Expansion Interface, the other to the TRS-80 computer. Once they are installed and the electrical cords are routed outside of the Expansion Interface, power can be applied.

This tells the user what to expect (they will have to open up the unit and install two power supplies inside it) and what the action accomplishes (that they can be powered on).

Here’s my take on providing the context for the second task (“Accessing the Ports on the TRS-80’s Expansion Interface”):

To attach any peripheral (printer, mini-disc, and other external devices) to the TRS-80 Expansion Interface the doors to the ports must be removed.

Simple, straightforward and to the point.

Detailing the Procedure
Here’s my stab at re-writing the first procedure about installing the power supplies within the body of the TRS-80 Expansion Interface.

  1. Locate and remove a door on the top-right side of the TRS-80 Expansion interface.
  2. Take the power supply with the DIN power connection and attach it to the motherboard. Place that power supply within the bay closest to the power motherboard power connection.
  3. Place the other power supply in the remaining bay, and lead the external power connections outside of the TRS-80 Expansion Interface through the slot provided.
  4. Place the door back on the unit.

Here’s my take on the second task about accessing the ports:

  1. Press on the right side of the door to the port you want to access. It will pivot slightly. Grasp the left side of the Door and pull it off.

That’s it, a single step. While I considered breaking this into two separate steps, the process is essentially a single action, so I made it one step.

Unfortunately I don’t have the benefit of an actual TRS-80 Expansion Interface, so my apologies if you are actually trying to following along to my instructions and find that they don’t make any real sense. However I hope the instruction is clear both in what has to be done and in what sequence.

Now I just have to write short descriptions for each task topic, and then add the appropriate tagging and I am done (for now). Here’s what the sample code looks like for these two task topics.

Task Topic #1:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="setting_up_the_power_supplies">
    <title>Use to set up the Power Supplies for the TRS-80's Expansion Interface</title>
    <shortdesc>How to set up the power supplies within the body of the Expansion Interface. Once
        this step is completed power can be applied to the system.</shortdesc>
    <taskbody>
        <context>
            <p>Two separate power supplies need to be installed within the housing of the TRS-80
                Expansion Interface. One provides power to the TRS-80 Expansion Interface, the other
                to the TRS-80 computer. Once they are installed and the electrical cords are routed
                outside of the Expansion Interface, power can be applied.</p>
        </context>
        <steps>
            <step>
                <cmd>Locate and remove a door on the top-right side of the TRS-80 Expansion
                    interface.</cmd>
            </step>
            <step>
                <cmd>Take the power supply with the DIN power connection and attach it to the
                    motherboard. Place that power supply within the bay closest to the power
                    motherboard power connection.</cmd>
            </step>
            <step>
                <cmd>Place the other power supply in the remaining bay, and lead the external power
                    connections outside of the TRS-80 Expansion Interface through the slot
                    provided.</cmd>
            </step>
            <step>
                <cmd>Place the door back on the unit.</cmd>
            </step>
        </steps>
    </taskbody>
</task>

Task Topic #2:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="accessing_the_port">
    <title>Accessing the Ports on the TRS-80's Expansion Interface</title>
    <shortdesc>Use to open the doors on the Expansion Interface to gain access to its ports. This is
        required in order to attach any peripheral device to the system.</shortdesc>
    <taskbody>
        <context>
            <p>To attach any peripheral (printer, mini-disc, and other external devices) to the
                TRS-80 Expansion Interface the doors to the ports must be removed.</p>
        </context>
        <steps>
            <step>
                <cmd>Press on the right side of the door to the port you want to access. It will
                    pivot slightly. Grasp the left side of the Door and pull it off.</cmd>
            </step>
        </steps>
    </taskbody>
</task>

Now we have two more draft topics for our revamped user guide. I say “draft” since there are some other DITA-related processing that can be added, but both of these can be considered complete from a writing perspective.

Next time: In the original there are also images that are used to illustrate where the power supply and port doors are located. That will be the subject of the next article in the series.

About

"DITAWriter" is Keith Schengili-Roberts. I work for AMD as a Senior Manager for Technical Documentation, and have recently helped usher in a new company-wide DITA-based CCMS. And I like to write about DITA and the technical writing community. To get ahold of me you can email me at: keith@ditawriter.com.

View all posts by

9 thoughts on “Thinking and Writing in DITA: Converting Legacy Content to DITA, Part 4

  1. What a nice transform of an addled text into to neat,easy to understand set of topics. One thought: I like to focus the short descriptions on task performance. How about: Use to set up … And Use to open the doors … These direct the user rather than simply describing the task.

  2. Thanks for the suggestions JoAnn! I have amended the short descriptions accordingly.

    Cheers!

  3. Pingback: Not Found
  4. Thank you for these articles.

    The wording of your short descriptions worries me (“Information about…”, “How to…”, “Use to…”). The DITA-to-XHTML and DITA-to-PDF transformations that I use render shortdesc as the first paragraph of a topic, with no highlighting to indicate that this paragraph is to be read as a standalone item of information (such as a summary – or “thesis statement” – of the topic).

    Your short descriptions work as standalone statements, but (in my opinion) not as introductory paragraphs.

    Consider the example from part 3, with the following text (the short description) rendered as the first paragraph directly after the topic title (“Overview of the TRS-80 Expansion Interface”):

    Information about what the TRS-80 Expansion Interface is and the peripherals that can connect to it. Includes basic information on how the peripherals can be used with the TRS-80 computer.

    This does not read correctly to me as an introductory paragraph that seamlessly leads on to subsequent paragraphs. Does it read correctly to you? (I have the same problem with your other short descriptions.)

    Perhaps the DITA transformations that you use do not render the shortdesc like this; perhaps your transformations somehow highlight the shortdesc, and set it apart from the body of the topic?

    Your thoughts?

    Nits:

    – For the title of task topic #1, was “Use to set up…” a typo? Did you mean to write something like “Setting up…”?

    – Nothing to do with DITA: on that same title, I might have chosen not to use the possessive form of “TRS-80” (I would have omitted the trailing “apostrophe s”). I tend to avoid using possessive forms of product names.

  5. I feel I should clarify my previous comment about your shortdescs…

    From the OASIS DITA 1.2 spec, topic 3.1.1.1.6, “shortdesc”:

    Do not use sentence fragments. Use complete sentences. Avoid starting short descriptions with phrases such as “This topic describes . . . .” or “This topic is about . . . .”

    Your shortdescs are sentence fragments; they lack subjects.

    Unfortunately, without completely rewriting them, simply inserting a subject would make your shortdescs self-referential:

    – “[This topic describes] information about…” or (removing the word “information”) “This topic is about…”

    – “[This topic describes] how to set up…”

    – “Use [this topic] to…”

  6. Very nice and useful information on writers starting out on DITA.
    Couldn’t find the next part in the series. Have you published it yet?

    1. Nope, have been busy with work so I have put this on hold for the moment. I *do* have the work on the SVG image/illustration done, which is arguably the hardest part. Now I just have to write the rest of it…

Comments are closed.