Thinking and Writing in DITA: Converting Legacy Content to 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.