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

This is a the third 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 Concept Topic
In the previous article I did a document review and determined how I could turn the existing content from the Radio Shack TRS-80 Expansion Interface Operator’s Manual (courtesy of Project Gutenberg), into DITA topics, along with determining which type of topics these would be. The article continues surveying the original material and then re-writing it according to Information Architecture and DITA best practices.

The first topic will be a concept, talking about what the TRS-80 Interface Expander is. Since it will be a concept, we need to answer what the TRS-80 Interface Expander is about, and what the reader can do with it. Unfortunately, there’s a bit of a problem that idea. Here are the first couple of paragraphs from the original version of the manual; see if you can figure out what the problem is:

The TRS-80 Expansion Interface consists of the Case, a DC Power Supply, a Ribbon Cable, a Cassette Recorder Jumper Cable and an additional Cassette Recorder Cable for Cassette Recorder number 2. Notice that the DC Power Supply is not installed in the Case upon receipt. It must be installed using the procedures under the heading “SETTING UP”.

The Case houses the Expansion Interface Printed Circuit Board (PCB), two DC Power Supplies and provides a housing area for an additional expansion PCB. The Expansion Interface utilizes a real-time clock and contains sockets for the addition of up to 32K of RAM in 16K increments.

While the first paragraph tells us about what it consists of, it tells us next to nothing about what the device actually is and what it can be used for. So we need to find that information. If this was a current product and I was in the company I could go and talk to the Subject Matter Experts (SMEs), or if I had access to the device I could spend some time investigating it myself (it is a consumer device after all). In this case though the information needed exists elsewhere in the manual – in fact, a following “Capabilities and Advantages” sub-section contains the nugget of what we need:

The Interface allows you to add the following Radio Shack modules to your system:

1. Screen Printer (26-1151)
2. Line Printer (26-1150)
3. Mini-Disk System (26-1160/26-1161)
4. Cassette Recorder number 2 (14-841)

The Screen Printer and Line Printer allow you to obtain hard copy (printed) information generated by your TRS-80.

It’s not perfect, but it does answer the question as to what the user can do with the TRS-80 Interface Expander. Editing this paragraph a little bit, we get the beginning of a good concept topic:

The TRS-80 Expansion Interface is for attaching additional peripheral devices to your TRS-80 computer. It is designed for use with Level II BASIC only; do not use with Level I. The following devices can be connected to it:

• Screen Printer
• Line Printer
• Mini-Disk System
• A second Cassette Recorder

The TRS-80 Expansion Interface houses an Expansion Interface Printed Circuit Board (PCB), two DC Power Supplies and there is space for an additional expansion PCB. The Expansion Interface utilizes a real-time clock and contains sockets for the addition of up to 32K of RAM in 16K increments.
Both the Screen Printer and Line Printer allow you to obtain hard copy (printed) information generated by your TRS-80 computer.

A Mini-Disk System provides access to a large amount of information that can be stored on a small floppy disc. Accessing data via the mini-disc system is much faster than by cassette recorder. The first disk contains roughly 80,000 bytes of free space for files, and each additional disk has 89,600 bytes of file space.

The use of two cassette recorders allows a much more efficient and convenient manner of updating data stored on tape. For example, if you have payroll data stored on tape, the information can be read, one item at a time, from Cassette Recorder number 1, then changed or added to and written out on Cassette Recorder number 2.

You must have a Level II BASIC TRS-80 Microcomputer to utilize the TRS-80 Expansion Interface, the Line Printer and the Mini-Disk modules. If you have a Level I BASIC machine, it must be modified to accept Level II programs.

Note: When the Expansion Interface is connected to the computer, it assumes that a Mini-Disk is connected. To use the Expansion Interface without a Mini-Disk, press the BREAK key on the TRS-80 keyboard. This will override the Mini-Disk mode and allow normal Level II operation.

That’s it. There is additional material in the original that talks about what parts comes with the unit, but I am going to include that material in the later “Parts List” reference topic.

Other significant changes include:

• Adding a line at the beginning mentioning that it is designed for use with a Level II BASIC system only, later reinforced with a paragraph at the end (derived from the original manual’s “Conclusion” section) that explains why.
• I have removed the part numbers from the original list. They are not important for the user to know at this point; this information will be present in the revised “Parts List” topic later.
• The list of peripherals is no longer numbered since this is information is not sequential.
• In addition to the list I describe—in the same order—what all of the additional peripheral devices can be used for.

So we now have the content for our first re-written topic which provides an overview of what the TRS-80 Expansion Interface is and what the user can do with it. A DITA Best Practice is to (re-)write material using minimalist techniques. While I am not as rigorous in my edit as I could be, the revised topic is still shorter than the meandering original section by more than 200 words.

Creating a Short Description for the Concept
Up until now there has been little mention of any DITA tags – it’s all been about how to think and re-write content based on DITA principles. Another recommendation for writing in DITA is to add a short description (using the appropriately named <shortdesc> tag in the header of a topic) within the header of each topic. It should not simply repeat the title of the topic; instead it should sum up what the topic is about. They are often used as description of the topic’s contents when used with the related-link mechanism to provide the reader with some information as to what is contained within the topic. In online help systems they are also sometime used to display “hover text” over a link for the same reason. The idea is to provide summary information about the topic to help the reader determine if the information they are looking for is there.

Here’s the text for my short description of this topic:

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.

That’s it, just a couple of sentences explaining what content can be found in the topic. I recommend that writers do this after they have written (or re-written) a topic rather than before, since you can only properly summarize the content once it is written. (Conversely some technical writers I know like to write this first so that they know what to content to add to the topic).

DITA Concept Sample Code
Now that we have the content, we can begin tagging it for DITA. This is only a first pass, as I will be doing more formatting work on this topic later, but the following ought* to be valid DITA:

<concept id="overview_of_the_trs80_expansion_interface">
<title>Overview of the TRS-80 Expansion Interface</title>
<shortdesc>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.</shortdesc>
<conbody>
<p>The TRS-80 Expansion Interface is for attaching additional peripheral devices to your TRS-80 computer. It is designed for use with Level II BASIC only; do not use with Level I. The following devices can be connected to it:</p>
<ul>
<li>Screen Printer</li> 
<li>Line Printer</li> 
<li>Mini-Disk System</li> 
<li>A second Cassette Recorder</li>
</ul>
<p>The TRS-80 Expansion Interface houses an Expansion Interface Printed Circuit Board (PCB), two DC Power Supplies and there is space for an additional expansion PCB. The Expansion Interface utilizes a real-time clock and contains sockets for the addition of up to 32K of RAM in 16K increments.</p>
<p>Both the Screen Printer and Line Printer allow you to obtain hard copy (printed) information generated by your TRS-80 computer.</p> 
<p>A Mini-Disk System provides access to a large amount of information that can be stored on a small floppy disc. Accessing data via the mini-disc system is much faster than by cassette recorder. The first disk contains roughly 80,000 bytes of free space for files, and each additional disk has 89,600 bytes of file space.</p>
<p>The use of two cassette recorders allows a much more efficient and convenient manner of updating data stored on tape. For example, if you have payroll data stored on tape, the information can be read, one item at a time, from Cassette Recorder number 1, then changed or added to and written out on Cassette Recorder number 2.</p>
<p>You must have a Level II BASIC TRS-80 Microcomputer to utilize the TRS-80 Expansion Interface, the Line Printer and the Mini-Disk modules. If you have a Level I BASIC machine, it must be modified to accept Level II programs.</p>
<note>When the Expansion Interface is connected to the computer, it assumes that a Mini-Disk is connected. To use the Expansion Interface without a Mini-Disk, press the BREAK key on the TRS-80 keyboard. This will override the Mini-Disk mode and allow normal LEVEL II operation.</note>
</conbody>
</concept>

This is fairly straightforward stuff, and anyone who has done any work with HTML wouldn’t be lost in this code. Since this is a concept topic it needs to be wrapped in the <concept> pair of tags, and I’ve added an id to it which will help identify it later. <title> and <shortdesc> follow, and then the content is wrapped with <conbody> tags (think: “concept body”). The individual paragraphs are surrounded by paragraph (<p>) tags and the list items by the unordered list by <ul> and <li> tags. The final paragraph is surrounded by <note> tags, which describes the type of content it contains. This is definitely not rocket science.

Next time: (Re-)writing a Task Topic.

* Am currently writing while on the go and am not using an editor with a validation checker. Hopefully my DITA-fu is up to par. 😉