Technical Writer

XML is the future.

You hear it at every conference you go to, in every magazine you pick up, in every article you read on-line.

For technical writers, right now that future comes down to two products—DocBook or DITA.

But what exactly are they, and which one should you choose?

They are schemas for creating XML.

What are schemas?

Think of them as blueprints, or templates, or even stencils. They are rules that tell you how to set up the xml.

The rules might be, for example:

• You must have a heading
• You may have a sub-heading if you wish, but it’s optional. If you do have a sub-heading, it must go immediately below the heading
• You must have one or more paragraphs of text
• You may include instructions. If you do include instructions they must be at the end. You should not include step numbers.
• You can add links to paragraphs or instructions, but not to the heading or sub-heading.
• Likewise, you can make the paragraphs and instructions, or part thereof, bold or italic, but you cannot make the heading or sub-heading bold or italic.

That’s a simple schema.

You may also come across the term document type definition (DTD). It’s a similar thing. Document type definitions are being replaced by schemas.

As a technical writer, how do you use DocBook or DITA then?

You write your documents in XML, making sure that the XML fits the DocBook or DITA schema.  Then any transformation file built around the appropriate schema can be used to produce end-user materials.

Why bother?

There are so many reasons but the main ones for technical writers are:

• Consistency, and
• Single source for multiple output.

For example, in the on-line help produced from the simple schema above you may only use the title and the instructions. In this case, the transformation file will only pick up the title and instruction elements from the XML. You may also produce a user manual which uses the title, sub-heading, all paragraphs and the steps.

You can use the same XML to produce the user manual both on-line and as a hard copy.

Likewise, all you need to do is change your style sheet and you can produce the help, an on-line user manual and a printed user manual for a different company.

The possibilities are limitless.

But what about DocBook and DITA?

You can create a schema from scratch, or you can use one that someone else has already set up for you.

DocBook and DITA have already been set up to do exactly what we do as technical writers. Rather than spend lots of time and money inventing something so similar to either or both of these, many technical writers have adopted one of these schemas as their standard.

DocBook was implemented by the publishing company O’Reilly & Associates and is particularly suited to books, in particular computer books.

DITA (Darwin Information Typing Architecture) was implemented by IBM.  It is more suited to tasks or topics, such as on-line help, or procedures.

Thus if you write book-length documents, consider DocBook. If you write chunked information, consider DITA. If you write a combination of both, the general consensus seems to favour DITA for this as well.

Last Modified : September 17th, 2006
Filed under : DocBook, DITA
Navigate : / Next post