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

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

One of the questions I am constantly asked by technical writers is: “how do I write using DITA?” The emphasis is less on the “DITA” part than the “writing” part. It is a fair question, since much of the focus up until recently has been more on the mechanics and less on the writing. Of course the two go hand-in-hand but even if you know each and every DITA tag it does not mean that you can automatically write effective DITA topics. To write well with DITA you have to “think in DITA” first.

One of the other barriers for new writers wanting to learn more about how to write their technical documents using DITA is the lack of good samples to work with. The “Radio Shack TRS-80 Expansion Interface Operator’s Manual” sample code that comes with the DITA-OT dates back to 2003(!) and it doesn’t cover much ground other than the absolute basics. Similarly some examples in the DITA books out there do not adequately reflect the type of content that many technical writers have to create. (An exception to this is the excellent Project Gutenberg, which outlines how to write a manual for an Espresso machine, and whose sample files are available when you register your book purchase at eReader versions).

Even when example code is available I haven’t been able to find one that looks the process of converting legacy content to DITA in detail and the thought processes that goes behind it. Given that most technical writers are not starting their work in DITA from scratch, comparing an example that has the “Before” as well as the “After” is useful as it doesn’t just show how to code, but how to write in DITA.

The obvious reason why this type of example is hard to find is the lack of appropriate legacy material to convert. Make no mistake, there’s a lot of legacy material out there, but the vast majority of it is proprietary and so not available as an example outside of the organization that originated it.

plain text Radio Shack TRS-80 Expansion Interface – CoverJust Don’t Call it “Trash”
But luckily I have found what I think is a good legacy example to work with that is freely available. It’s an oldie-but-a-goodie: the eReader versions, courtesy of TRS-80.org.

It is no longer in copyright so it is freely available for anyone to work with. The manual is short (11 pages not counting the front- and back-cover) so it is easy to digest. It is a manual that was shipped with a computer hardware product, a situation many contemporary technical writers using DITA today still face. While the manual is old (circa 1979!) and I doubt anyone is grappling with the issue as to which cassette recorder is the best for storing data these days, in form it is not so different from more contemporary technical documents. Versions of this document are available on the Project Gutenberg site in eReader versions, TRS-80.org and various eReader versions.

While I don’t have direct access to any Subject Matter Experts (SMEs), the TRS-80 community is still surprisingly vibrant, and additional material on this piece of hardware is available on the TRS-80.org and eReader versions sites, where I have done additional research into the background for this and related devices.

The Document Audit Process
Before any writing is done the Information Architect/Document Architect ought to survey the material first. While the Expansion Interface manual is the only one available from Project Gutenberg, other publications in support of the TRS-80 are still available; there is a collection of them available from the 1000bit.it site at: http://www.1000bit.it/scheda.asp?id=110.

What’s available there can be sorted into three broad categories: End-user Manuals (e.g. “User’s manual for level I”), Technical Manuals (e.g. “Internal memory installation instructions”), and Software Manuals (e.g. “Introduction to TRS-80 Level II Basic and computer programming”). The manual I am working with falls squarely under the End-user manual category.

While reading the material the questions I asked myself included:

• What audience is this intended for?
• What scenario(s) are readers likely to be using this manual?

It is clear to me that the audience for this manual is someone who is relatively technically savvy, but not (necessarily) an electrical engineer. Much of the manual deals with the types of connections that are available, so it is not so different than a manual that covers all of the inputs and outputs for a modern flat-panel television. The tone of the manual is slightly more technical than you are likely to see today, with a lot of talk about the memory capabilities or throughput of the various peripherals that can connect to it. This information is not necessarily important to anyone who just wants to hook everything together, but there is clearly an educational aspect to some of this content, telling the customer what aspects of peripheral devices to look for.

As for when and what circumstances this manual would be used, it is clear to me that anyone who bought this would have immediately wanted to connect it to their TRS-80 and likely attach at least one peripheral to it. The manual would also likely be used more than once, after the reader has bought additional peripheral devices to attach to the computer.

Normally a Document Architect would also come up with a fully-described persona/scenario for this manual set, but in this case let’s simply assume the following:

• The reader has just purchased the Expansion hardware and is looking to attach it to their TRS-80 or is looking to install an additional peripheral some time later.
• Can be considered relatively technically savvy, and likely an “early adopter” of technology who finds additional technical detail useful.
• Is likely a hobbyist or is using this computer hardware in a small business – which is in keeping with the time in which this was made – which again supports the idea of the reader being more technically-savvy than most.

From a DITA perspective one of the other things I am looking for are similarities in content for reuse between end-user publications. Frankly these documents are all idiosyncratic, so all of the documents would need a thorough re-write for consistency’s sake. The move from unstructured to structured content often requires re-writing the original material. In many cases a re-write is a prerequisite in moving legacy content to DITA if you are seeking better reuse rates for it in other documents. So while there’s more work at the outset when moving legacy content over to DITA, the results not only de-silo the content but also improve the opportunities for content reuse by later publications.

Next time: I will do further analysis of the legacy material document and create a new structure for it which will go into a DITA map.