Writing For Reuse (or Carefully Crafted Content)
Your department has decided to switch to DITA. Scary isn’t it? But, it doesn’t have to be. As an author, you need to embrace these changes and advocate for the future of documentation. In a recent survey done by SDL, more than 18 percent1 of companies who responded are moving into XML and a significant portion of those are moving specifically into DITA. Some are moving just because XML and DITA are the buzzwords of the day and they have no clear plans or specific methodology in mind. Of course “we” don’t work for those companies; we work for a company who is approaching the problem in a sensible manner with a proper plan and proper research into the documentation content, as well as the documentation processes and procedures…don’t we?
Ahh…hem, well yes, in an ideal world perhaps, but most of the companies I come into contact with, as a consultant, are concentrating entirely on the technical changes and implementation of the “new environment” and ignoring the key factor in making the system work. This key factor is, as all authors will know, getting the content right in the first place. In this article, I want to explain how we, as authors, can develop a methodology that fits well into the “new environment” and will ensure reuse of our carefully crafted content.
Carefully Crafted Content
What does “carefully crafted content” mean? With the methodology I describe below, you will soon understand. It is all about the level of detail in a module, knowing where to set the boundaries, and making decisions about when to create a separate module or chunk.
The technical guru’s talk about “granularity,” but most of them don’t really understand documents; they are technicians, not writers. So, their idea of “granularity” is not in line with the concepts of usable documentation.
Most of the time, when we start to look at a new manual or book, we think about the Table of Contents—what do we need as headings and sub-headings to convey the information clearly to the reader. Having decided on the structure of the Table of Contents, we then set about filling the sections with content, starting with the first chapter and working our way to the end of the document. This methodology is a logical approach for conventional documentation. However, it does not lend itself well to “writing for reuse.”
The first step—identifying the chapters, subsections, and headings for the Table of Contents—is a good one. It helps us form an idea of how the manual will look when it is finished. To write reusable content, we now need to start at the bottom-most level of the Table of Contents and write our first modules from the bottom up, rather than the traditional method of writing from the top down.
Let’s say we have to write a service manual for a piece of hardware (as illustrated in Figure 1). It is a box, with a rack inside it, and in the rack are a number of computer boards that might need servicing. It also has a power supply and a control panel. Traditionally, we would start by describing the function of the box, then perhaps the rack, and finally the boards, power supply, and control panel. But, because we are always thinking of the boards as the items of interest, this affects the way we write the higher levels. We will soon want to start naming the boards and describing their functionality way too early in the documentation. In 6 months time, the board gets changed and now we have to look at the whole book and change the data in multiple places with multiple modules, and we risk the chance of missing one or more references.
Figure 1: Carefully Crafted Content Methodology
If, however, we had started at the board level and created a stand-alone DITA module for the board, then at higher levels we can refer to that specific module in a more generic manner. So, when the board changes, we have only one module to update without fear that the rest of the chapters or sections also need to be altered (or maybe even create a parallel module that can then be substituted into a ditamap or bookfile to create the new version).
Level of Abstraction
The level of abstraction, as outlined in Figure 2, describes how abstractly you need to write about the items lower in the Layering Concept model. So, at the top level, the abstraction is great, and as we progress down the document to the bottom level, the level of abstraction is reduced to specifics.
Figure 2: The Layering Concept
Level of Specific Detail
The level of specific detail in the Layering Concept model is higher the closer you get to the center of the diagram and lower as you move up and to the edge of the diagram.
When writing a module for a board, the specifics of the board can be explicit—things like its order number, manufacturer, size, and operating parameters. At higher levels (2, 3, & 4 in this model), we should only refer to the board as a generic item, such as “the processor board” or the DSP board. These names should be detailed in a terminology list or in a terminology database so that anyone writing modules for a higher level will use consistent naming conventions when referring to the same item. This facilitates reuse without rewriting. For example, in the board level module for the DSP board, the content can speak to the specific DSP board (model DSP1234 from DSP Solutions, Inc), and the terminology list would contain an entry like DSP1234 —The DSP processor board.
Writers wanting to refer to this board at a higher level should use the “The DSP processor board” words to describe it, and not the “DSP1234” because it might change, but the function will still be the same, even if the board changes to a DSP2345. The module describing the DSP1234 board should also contain both terminology list entries so that the reader is not confused—The DSP processor board—DSP1234.
Likewise, when the boards are in the rack, at the sub-subsystem level, their positions need to be explained to the reader. This explanation should be handled with the terminology list names and not with the specific name. But the specific manufacturer, the dimensions, and characteristics of the board rack can be explicit at this level.
One level up from level 3 in the diagram, the rack and its boards are referred to as a “board rack”—according to the terminology list and never as the “Veroboard model 500 VME bus rack”—for example. On the top level, the description of the function of the system is outlined but in terms that are non-committal to specifics of the build-up of the system.
Here, perhaps the color of the cabinet could be mentioned as being blue and, in the module pertaining to the cabinet itself, the exact RAL color of blue might be specified. However, this specification could lead to problems if the color is changed to red for marketing or manufacturing—perhaps we would have to weigh the possibility of change before making a commitment about the color at the system level.
The Terminology List
The terminology list is one of the most important tools for maintaining consistency between modules and layers in the Layering Concept model. It must be available to all authors and be maintained in a controlled manner (perhaps with change-control software). Usually it is the responsibility of the editor to maintain and manage the terminology list.
Apart from the names of hardware items, the terminology list should also contain phrases that ensure consistency—for instance, one author writes “ the flange on the widget is bolted to the sub-assembly with a #4 bolt” and another author writes “to remove the sub assembly, loosen the fixings on the wadget and slide the sub assembly up.” If these two pieces of text are seen together, confusion will arise—is there a difference between a sub-assembly and a sub assembly, between a fixing and a bolt, or the widget and the wadget?
The level of detail in a DITA Module (DM) is a key factor in the reusability of the DM in different configurations and products. The DM is not as reusable if the level of detail is too deep, compared to a module that is a higher level view. The more reuse we can obtain from a module, the cheaper the manual is to produce and the more time we all have to work on other projects.
Concentrating on the content of a DM instead of the structure and layout also frees time for research and writing. (And, after all, that is the fun part of our job!)
So, how do you decide what level of detail is enough and what level is too much or too little. This decision can be difficult, but the key idea to remember is that the DM has to be able to stand alone. This idea usually gives you insight to the correct level of content. If it starts to drift away from stand-alone, then it is time to create another DM.
If you need to create more than one module for a level, then you can chunk them together. Multiple modules may be prudent if your company makes many products that use the same component parts but with different configurations.
Examine the following: The PB999 processor board is a general-purpose motherboard with SCSI, Ethernet, serial ports, and USB connections used in many different products.
In product A, they use the SCSI bus and the USB bus but not the Ethernet or Serial ports. In product B, they use all the ports. You could write two modules, one for each product, you could write one module and use “conditional processing” to show or hide the component parts, or you can take the third approach to create a base module describing the motherboard and show a block diagram. In the description, you might mention that items not listed are not used in this product. Create modules for each of the options in such a way that each one is the lowest, complete, stand-alone unit of information. Create two map files with the correct content for each configuration. Link these maps to the bookfiles.
Now, if the SCSI connector changes from a 25-pin D-type to a sub-mini, you only have to update the one SCSI-bus DITA module. If the board changes its name, manufacturer, or size, then you only need to change that module—the rest will still be valid and not require re-work. If a new product uses 3 of the 4 connectors, you can build the map in seconds and your work is done.
1 Rate is per survey article submitted by SDL
David has been involved with documentation solutions for more than 20 years, he has recently joined Thales Nederland to work on their S1000D implementation. Defining the Business Rules and the Style and also writing DataModules, XSLT and XSL FO to transform S1000D into manuals. Before that, David was with NXP Semiconductors (ex Philips) for 9 years, developing documentation solutions and pioneering the change to database XML and DITA document generation. He has a wide experience of solving documentation problems and even has his own company —MIFMasters—which deals with bespoke documentation solutions. His company has just finished a project for a DITA Differencing Tool (DDT—a killer application). He can be contacted via PB6X@qsl.net or firstname.lastname@example.org.