Why Switch to Structured Documents?

Why Switch to Structured Documents? 

Which Structured Document Standard?

Getting started

Why Switch to Structured Documents?

• The clean separation between content and presentation allows you, as a technical writer:
  • to concentrate on what you write and forget about how it will look like,
  • to delegate presentation to typesetting experts,
  • to be confident that you'll get beautifully typeset deliverables at the push of a button,
  • to be confident that these deliverables will be visually consistent (logos, fonts, etc) with all the documentation produced by your company.
• Even the most advanced word-processors lack the high-level constructs often needed when you write technical documents. For example, you'll not find the equivalent of DocBook programlisting+co+calloutlist.
• By using multiple node selection rather than text selection, you'll be able to directly manipulate the structure of your document and this, without having to switch back and forth between the normal view and the outline view.
• The structured approach encourages the creation of modular documents. DITA example: you'll want to create files containing individual topics. DocBook example: you'll want to create files containing individual sections or chapters. And, of course, this modularity allows several writers to efficiently and safely work on the same documentation at the same time.
• The structured approach makes it easy automatically generating variations of the same documentation. For example, a single structured document may contain the documentation of variations A, B and C of product P. (This is called profiling in DocBook parlance.)
• The Schematron technology allows to enforce writing rules. With a Schematron schema, you can ensure, for example, that all your DocBook books start with a sect1 having "Disclaimer" as its title.
• The structured approach makes it easy automatically generating a part of the documentation source. Example: automatically extract a part of the reference manual out of the source code of a software.
• A single source, XML, allows to generate deliverables in a variety of formats: HTML, XHTML, HTML Help, Eclipse Help, Java^TM Help, PDF, PostScript®, RTF, WordprocessingML (MS-Word 2003), OpenOffice (.odt, native format of OpenOffice.org 2), Office Open XML (or OOXML, .docx, native format of MS-Word 2007).
• Structured documents are easy to translate: keep the structure (elements, attributes, etc) and replace the text (i.e. the characters) and the screenshots by translated text and ``translated'' screenshots.
• Structured documents are perennial. They are based on well-documented, de jure standards. They are supported by a wealth of software vendors and Open Source software.

Which Structured Document Standard?

Latest version of DocBook 4 without any doubt. DocBook 4 is a mature document type, well-documented (DocBook: The Definitive Guide, DocBook XSL: The Complete Guide), coming with decent XSL stylesheets allowing to convert it to a variety of formats.

Why not recommend the following document types?

DocBook 5

DocBook 5 is unquestionably technically better than DocBook 4 but it is ``still in the beta''. We'll probably recommend DocBook 5 over DocBook 4 in the near future.

If you have started authoring your documents in DocBook 4, well, change nothing: there are no compelling reasons to convert your DocBook 4 documents to DocBook 5. However, if, for any reason, you wanted to do that, you would easily find an XSLT stylesheet (part of the DocBook 5 package, included in the DocBook 5 add-on for XXE) to perform this conversion.

DITA

DITA concepts (topics, maps, specialization, etc) have an immediate appeal to the technical writer and indeed, makes this document type more attractive than DocBook. However, in our opinion, there are two problems with DITA which make that we cannot recommend it for production use:

1. The DITA vocabulary is currently evolving (current version of the DTD is 1.0, with version 1.1 to be adopted as a standard by OASIS in the near future).
2. DITA documents are converted to a number of formats by the means of the DITA Open Toolkit (included in the DITA add-on for XXE). Currently, what's produced by the DITA Open Toolkit leaves much to be desired.

XHTML

XHTML with its 70+ elements is not expressive enough to write complex technical documentation. However, it is a great choice if you just need to write unadorned Web pages (e.g. you contribute pure content which is to be dressed up by the CMS hosting it) or if you just need to write online help.

Getting started

1. Learn the basics of XML: what is an element, an attribute, a text node, etc.
2. Download and install free-to-use XMLmind XML Editor Personal Edition.
3. Read the tutorial of XMLmind XML Editor (this chapter uses an XHTML document as an example, but everything you'll learn there applies to DocBook, DITA or any other type of document). Also read the "Being productive" chapter.

   If you don't like reading documentation, then watch this Flash demo a couple of times.

4. Start right away writing your first DocBook document.

   No need to learn DocBook: DocBook element names are highly descriptive and XMLmind XML Editor ``knows'' the DocBook grammar for you.

   However, you must start thinking in terms of semantics and be aware that DocBook with its 400+ elements almost certainly has an element which corresponds to the semantics you want to express. Example: you have typed word "mashup" and are tempted to select it and to convert it to an emphasis element because "mashup" is a new concept you are going to explain in the subsequent paragraphs. Restrain yourself for doing that: DocBook has a firstterm element which will do here a much better job than emphasis.

   When you are not sure of the meaning of a DocBook element, then it will always be time to consult this reference "DocBook: The Definitive Guide".