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

Thinking and Writing in DITA, Part 2
Thinking and Writing in 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:

Comparing the Sections of Two TRS-80 End-user Manuals
Comparing the Sections of Two TRS-80 End-user Manuals

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.

Getting the DITA Topic Types Right (Adapted from Original TRS-80 Cartoon)
Getting the DITA Topic Types Right (Adapted from Original TRS-80 Cartoon)
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 TitleRevised DITA Topic TitleTopic Type
IntroductionOverview of the TRS-80 Expansion InterfaceConcept
Capabilities and Advantages""
Power Supplies and PCB HousingSetting Up the Power Supplies for the TRS-80's Expansion InterfaceTask
"Setting Up the PCB Housing for the TRS-80's Expansion InterfaceTask
Electrical ConnectionsTRS-80 Expansion Interface ConnectionsConcept
"Connecting the TSR-80 Computer to the Expansion InterfaceTask
"Connecting External Power to the TRS-80 Expansion InterfaceTask
"Connecting a Data Cassette Recorder to the TRS-80 Expansion InterfaceTask
OperationPowering On the TRS-80 Expansion InterfaceTask
ConclusionAdditional Information About the TRS-80 Expansion InterfaceReference
Parts ListParts List for the TRS-80 Expansion InterfaceReference

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!

About

"DITAWriter" is Keith Schengili-Roberts. I work for IXIASOFT as a DITA Specialist/Information Architect. 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

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

  1. Your idea of applying IA principles to bringing legacy information into a topic-oriented world is so useful for writers, Keith! I appreciate seeing the insights in your approach to the task. I too am looking forward to the next episode.

  2. Thank you Don! I *may* get to some actual DITA code by article #4, possibly #5; up until then I will concentrating on the IA/re-writing aspects of things.

Comments are closed.