Skip to content
Olivier CarrèreTechnical writing practice

Formats and tools

Concept
DITA XMLStructured authoringTechnical writing

When industrializing technical writing, the format matters more than the tool. Compare proprietary formats like Word and FrameMaker against open standards like DITA XML and DocBook to find the right fit.

, 1 min read

View as Markdown

Definition

Section titled “Definition”

When a company sets out to industrialize technical writing, the question of tools comes up immediately. The real issue, though, is the underlying format, not the tool.

Many vendors have built proprietary formats that only their own software can edit, locking in a captive market that has to keep paying for upgrades. An MS Word or FrameMaker file, for example, can only be edited in the tool that created it. Committing to such a format narrows a company’s options and can get expensive: every user needs a license - technical writer, occasional contributor, and translator alike.

A standard format leaves the choice of tool openDiagram showing four different tool types, a text editor, open-source software, a graphical tool, and proprietary software, all able to edit the same standard DITA XML format.Text editorOpen-source softwareGraphical toolProprietary softwareDITA XML

A standard format leaves the choice of tool open.

Key principles

Section titled “Key principles”

Focusing on the format instead opens the door to scalable solutions. An open format - OpenDocument, or DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → (the only one of the two designed as an industrial format for technical writing) - isn’t tied to any single tool, so it can be edited and processed by many. And because the source format shapes the entire production chain, that choice carries more weight than any tool decision. Structured formats such as DocBookA semantic XML markup language for technical documentation, organized in books, chapters, and sections rather than typed topics. It predates DITA XML and is the usual point of comparison when choosing a structured format.View in glossary → and DITA XML, governed by a standard XSD (XML Schema Definition)The W3C schema language for XML, itself written in XML. DITA XML's XSD schemas define which elements each topic type allows; a file that breaks them fails validation, which also constrains what conrefs and conditional text may produce.View in glossary → SchemaA formal description of the structure a document or data file must follow: which elements or fields are allowed, in what order, and with which values. Validating content against a schema (DTD, XSD, or RELAX NG for XML; JSON Schema for JSON) catches structural errors before publication.View in glossary →, can be handled from authoring through publication by a wide range of software, from free text editors to proprietary graphics suites.

Section titled “Related articles”
Section titled “Related reading”