XMLmind logoCompany | Contact | Site Map
 
 

Why Switch to Structured Documents?

item Why Switch to Structured Documents? 
item Which Structured Document Standard?
item Getting started

Why Switch to Structured Documents?  Back to TOC

  • 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, JavaTM 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?  Back to TOC

Answer: DocBook 5, if you have simple to intermediate documentation requirements; DITA, if you have intermediate to advanced documentation requirements.

item DocBook 5 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, based on the best schema technologies: RELAX NG and Schematron.

item DITA concepts (topics, maps, etc) have an immediate appeal to the technical writer and indeed, makes this document type more attractive than DocBook. However the learning curve of DITA is steeper than DocBook's, especially if you need to specialize DITA in order to extend its standard vocabulary.

Why not recommend the following document types?

DocBook 4
DocBook 5 is unquestionably technically better than DocBook 4. For example, unlike DocBook 4, DocBook 5 allows you to embed SVG graphics and MathML equations in your document.

However, if you have started authoring your documents in DocBook 4, we don't recommend to convert them to DocBook 5.

Note that, if for any reason, you wanted to do that, simply use File|New to create a new DocBook 5 document (in order to activate the DocBook 5 configuration in XMLmind XML Editor), then select menu item DocBook|Convert to DocBook v5+ then Open, then choose the DocBook 4 document to be converted.

XHTML 1
XHTML 1 with its 70+ elements is not structured 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  Back to TOC

  1. Learn the basics of XML: what is an element, an attribute, a text node, etc.
  2. Download and install XMLmind XML Editor Evaluation Edition.

  3. Follow this tutorial. It is organized in largely independent, short, lessons. Almost all lessons contain a short (less than 1mn) screencast. Take at least the first few lessons.

    If you find the above tutorial too comprehensive and don't have enough time to follow it, we recommend to read (no screencasts) this minimal tutorial.

  4. Start right away writing your first DocBook document.

    No need to learn DocBook: DocBook element names are self-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".