What I Would Do if I Have a Magic Wand

What would I do with technical documentation if I had a magic wand? Actually, I would do 2 things, one for myself and one for clients:

1. I would make documentation easy to write (for myself)

2. I would make it easy to read (for clients)

But nobody made me such a gift and I have only the words from Everly Brothers’ Dream song ringing in my ears:

Only trouble is, gee whiz
I’m dreaming my life away

DITA can be a good solution, but moving to DITA is not going to be an easy task. Scott Abel, a content management strategist, posted an article called “10 DITA Lessons Learned From Tech Writers in the Trenches”.

In Lesson #1, he wrote: “DITA changes everything. So, ask yourself, ‘If I change everything about my life, how long will it take me to adjust to those changes? How much time, work, and money would be involved? And, would every change I made be a good decision?’ If you plan to move to DITA, be ready for some pretty major changes.

So maybe something less scary, but still effective can be done? After all, DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s. Among many others, I would mention Sequential Thematic Organization of Publications (STOP) and Structured Writing.

The main principles of these methods do not depend on an authoring tool. You can use Word, FrameMaker, RoboHelp, Flare, or something else – the principles remain the same:

1. Modularity. Chunk your content into relatively small portions of information. Don’t overload a reader with tons of information – keep each chunk focused on one specific subject that helps a reader achieve one specific goal.

Technically, each chunk represents a single file. You can later arrange individual chunks into deliverables.

2. Labeling. Explicitly label chunks and content within chunks to let readers easily navigate across and within chunks. For example, if a chunk contains too much information, and this information cannot be split into separate chunks, divide the chunk into sections and give each section a title.

Similarly, think about tables as a much more effective way to organize and information than writing long narrative texts.

3. Context independency. Potentially, each chunk can be used in multiple deliverables. Moreover, the same chunk can appear on different levels of the hierarchy in different deliverables. ip Keep this in mind and write content in a way that makes sense on its own, that can be reused as a stand-alone topic, and thus, doesn’t depend on the surrounding content.

4. Information typing. Classify chunks based on the type of information they provide. The structured writing method suggests using 7 information types:

  • Procedure
  • Process
  • Concept
  • Structure
  • Classification
  • Principle
  • Fact

DITA narrows this list down to only 3 default types: concept, task, and reference.

You can use any of them or invent your own ones, but the point is: investigate your content and understand the structure of each information type.

5. Consistency. Create a template for each information type (for example, using Word or FrameMaker). ubuntu ftp server This template establishes a structural framework that defines information to be described in each type. When creating a new chunk, you will use an appropriate template depending on chunk’s type.

6. Mapping. This is when you arrange all the individual pieces into a readable document for your clients. Stand-alone chunks become a document through:

  • Arranging them into collections (also known as maps) according to a certain criteria. For example, you can put together chunks that belong to the same information type. You can also group chunks according to goals a user can achieve reading the information. You can later arrange these individual maps into a bigger map that represent your deliverable.
  • Establishing links between individual chunks for providing the most complete information on a subject matter. For example, you can link a procedure to chunks that provide conceptual information that a reader must know to accomplish this procedure.

The truth is that these principles are not related to the Structured Writing method only. They relate to a good technical writing as well. You may notice that unconsciously you are already using them in your work. Well, in this case, maybe it’s a good time for you to begin thinking about tools that support your processes and enable you to do the same, but more effectively. And if you are not practicing a methodology, investigate your content and determine whether you and your clients can benefit from implementing the principles of structured writing.