Structured Documentation – Is it right for you?

A structured document is an electronic document whose contents are organized into labeled blocks according to certain restrictions—known as schema—using a mark-up language such as HTML or XML. Rather than formatting with presentation to end-users in mind, structured documents give priority to grouping information together logically. When used in the right situations, it can make document contents easy to search, update, and reuse. However, many businesses will find structured documentation inefficient and not worth the trouble of implementing.

Why Should I Use Structured Documentation?

The labeling of sections in structured documentation makes it easy to lift sections from one document for use in another. A device compatibility table, for example, might also be used in copy, such as sales brochures, on the company website, or in manuals for similar devices. When information in the table requires updating, a technical writer need only update a single copy to make that change in many different documents at once.

This is especially useful for translated projects. The updated section needs only be translated once by a single translator, increasing efficiency and preventing potential inconsistencies between documents. As an added bonus, all translation memory systems use XML, so this format will be useful for any larger translation project.

What’s Wrong with It?

That said, structured documentation requires heavy investment, and is not ideal for every organization. To be efficient, writers need training and experience with the interface they will be using (DITA, DocBook, Solbook, etc.). Training all employees involved in documentation can be a difficult investment of time and money.

If changes need to be made to document contents on a larger scope, such as a product line splitting into two different product lines, it can cause major headaches. Not only do writers need to assess which products (and all corresponding documentation) will be updated to be parts of which product line, they also need to be ready to make appropriate changes using a system with a steep learning curve.

Finally, there is one other hurdle to jump before implementing structured documentation: templates for publishing. There are open-source templates out there, but companies will likely need to invest time and money designing templates for individual solutions.

In brief, use structured documentation if…

• Your firm has extensive documentation.
• Large amounts of content will be reused.
• Documentation needs to be published in a wide variety of formats.
• Content will require frequent updating, but formatting can remain consistent.
• The project involves translation.

For a closer look, see CSOFT’s blog entry about DITA, a popular architecture for structured documentation.

Written by Peter Edberg – Technical Writer at CSOFT International