Why Switch to Structured Documents? Why Switch to Structured
Documents? Which Structured Document
Standard? Getting started
- 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.
Answer: DocBook 5, if you have simple to
intermediate documentation requirements; DITA,
if you have intermediate to advanced documentation requirements.
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.
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.
- Learn the basics of XML: what is an element, an attribute, a text
node, etc.
- Download and install XMLmind XML Editor
Evaluation Edition.
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. - 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".
|