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

This is the second 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.

Legacy Document Review
In the previous article, after determining the audience and scenarios in which the original Radio Shack TRS-80 Expansion Interface Operator’s Manual, (courtesy of Project Gutenberg) was likely to be used, while also identifying its place within its related document set (End User Guide) and looking for reuse opportunities. Now we need to dig bit deeper within this document to determine its existing structure, how that compares to other manuals in its document set, and how to restructure it.

I have converted a lot of legacy content to DITA, but I don’t think I have ever run across an example so closely tied to the narrative style than this manual; not only does it have an “Introduction”, it even has a “Conclusion”! While there is no handy Table of Contents that lays out its structure, the existing framework for the document—its sections and sub-sections—looks like this:

Cover
Introduction
– Capabilities and Advantages
Setting Up
– Power Supplies and PCB Housing
– Electrical Connections
Operation
Conclusion
Parts List
Limited Warranty (Legal Disclaimer)
(Publication Information)

Looking for possible reuse opportunities, I then compare this to similar End User documents (available from 1000bit.it and TRS-80.org. The other manual this is most similar to is the Expansion Interface Manual. Here are their two ToCs compared side-by-side:

Notice that I am including their respective Covers and Limited Warranty sections. These will both be dealt with separately in future articles when dealing with tweaking the document output from the DITA-OT.

The only other match is the “Setting Up” sections in both documents. Examining this section in both manuals reveals that a lot of the same technical images are being reused, but virtually none of the text. The Setting Up section in the longer Expansion Interface Manual is more thorough and arguably better-written, so my inclination is to re-write the material in the shorter Expansion Interface Operators Manual for reuse where possible between the two publications. Note that this does not mean that I am planning to copy the content from the Setting Up section from the longer manual; it means that I will re-write the existing section so that I could likely re-use it in the longer manual which would also need to be revamped in order to move it to DITA. This is not re-writing just for the sake of re-writing, it is re-writing with an aim to improving the content while also moving it to DITA.

Typing the Content and Descriptive Titles
The next stage is to read through the material again and determine which DITA topic types are the most applicable to the content. Now I am looking at the text with an editor’s eye, not only trying to fit topics into the right slots, but thinking about what information needs to go into each topic so that I am not forcing a square peg to go into a round hole, so to speak. This means that some sections in the original manual may disappear, and other sections may become more than one topic, following the plan of “one idea = one topic”.

Considerable emphasis is placed on having more descriptive titles for DITA topics. This not only makes them easier to find when put into a DITA CMS, but it also helps other writers more easily identify whether a given topic is a good candidate for reuse. As a writer, imagine the hassle of finding a couple of dozen topics called simply “Introduction” and then having to look through them until you find the one you want. By breaking down each idea into a single topic that has a descriptive title, the reader can better zero in on exactly the portion of the document they want to review.

Rationale for the New Titles
Going over the material for this manual, I have come up with the following revised DITA topic titles and types:

Original and Revised DITA Topic Titles and Types

Original Title	Revised DITA Topic Title	Topic Type
Introduction	Overview of the TRS-80 Expansion Interface	Concept
Capabilities and Advantages	"	"
Power Supplies and PCB Housing	Setting Up the Power Supplies for the TRS-80's Expansion Interface	Task
"	Setting Up the PCB Housing for the TRS-80's Expansion Interface	Task
Electrical Connections	TRS-80 Expansion Interface Connections	Concept
"	Connecting the TSR-80 Computer to the Expansion Interface	Task
"	Connecting External Power to the TRS-80 Expansion Interface	Task
"	Connecting a Data Cassette Recorder to the TRS-80 Expansion Interface	Task
Operation	Powering On the TRS-80 Expansion Interface	Task
Conclusion	Additional Information About the TRS-80 Expansion Interface	Reference
Parts List	Parts List for the TRS-80 Expansion Interface	Reference

The original manual’s “Introduction” actually provides more of an overview of the product, and can be comfortably categorized as a concept topic. The useful content in the following “Capabilities and Advantages” section will be rolled into the previous concept topic. (Some of the content from the “Conclusion” section will also be added to this topic, but more on that later).

For now I am dropping the “Setting Up” section as it strikes me as being an unnecessary division in such a short document, though I may revisit this later.

The “Power Supplies and PCB Housing” section actually contains information on two separate tasks, which will be called “Setting Up the Power Supplies for the TRS-80’s Expansion Interface” and “Setting Up the PCB Housing for the TRS-80’s Expansion Interface”.

I find the following “Electrical Connections” to be a bit of mess, and in trying to untangle its content I have found the basis for four separate topics:

• “TRS-80 Expansion Interface Connections” (Concept)
• “Connecting the TSR-80 Computer to the Expansion Interface” (Task)
• “Connecting External Power to the TRS-80 Expansion Interface” (Task)
• “Connecting a Data Cassette Recorder to the TRS-80 Expansion Interface” (Task)

The “Operation” section is really all about how to turn its electrical power on, so I have renamed it “Powering On the TRS-80 Expansion Interface”. The “Conclusion” section contains information which is better placed at the beginning of the document, and what remains is additional information about the unit, hence the new topic title: “Additional Information About the TRS-80 Expansion Interface”. The “Parts List” section is exactly that, so its title is expanded to “Parts List for the TRS-80 Expansion Interface” and will be typed as a reference topic.

Gerunds for Task Titles
Note that I am also using active voice where possible, resulting in most of the titles using active gerund “-ing” verbs: “Setting” instead of “Set”, “Connecting” instead of “Connect”. These new titles imply action, and you may have noticed that the active “-ing” words are used for all of the revised tasks titles; this is recommended practice for DITA task topic titles.

Now I might be criticized for adding “TRS-80 Expansion Interface” to most of the titles, but my intention for now is to make each of these topics distinct and specific to this product. While this limits the reuse possibilities – for example I might be able use the “Powering On” topic for another product – I can change this later by substituting the name of the product in the titles with a key or conkeyrefs later (similar in operation to a “variable” in FrameMaker). For now I am simply striving for clarity of purpose.

Next time: the re-writing begins!