Skip to content
Olivier CarrèreTechnical writing practice

Choose an authoring model

Tools, formats, trade-offs, and selection criteria for technical documentation.

1 min read

View as Markdown

The decisions that shape everything else: how much formal structure your content needs, how to reuse it, which Source formatThe format content is authored in, as distinct from the target format it's published to — the recipe versus the dish.View in glossary → to write in, and which Target formatThe format a reader actually consumes — PDF, HTML, compiled help — generated from the source format.View in glossary → to publish to.

Structured content principles (separating content from presentation, typing information by reader intent, writing reusable modules) apply to almost every documentation project. What varies is how strictly they are enforced. DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → enforces them through a 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 → and a dedicated toolchain; MarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary → in a Docs-as-codeTreating documentation like source code: text-based formats, version control, code review, and CI/CD, rather than a separate publishing process.View in glossary → workflow applies them by convention, templates, and automated checks. Neither is obsolete: different projects need different levels of formal structure.

Markdown

Section titled “Markdown”
Markdown as a source formatA lightweight, versionable source format that sits between word processing and structured XML.
A well-structured Markdown pageAn annotated concept article, explaining each structural choice.

Structured authoring

Section titled “Structured authoring”
Use structured authoringDITA XML, information typing, content reuse, and modular content models — with real-world case studies.
Structured vs. unstructured formatsThe foundational choice that determines reuse, translation cost, and tooling.

DITA

Section titled “DITA”
Structured DITA XML formatReduce production costs and delivery time in technical documentation by choosing the right format, structured authoring approach, and modular content reuse strategies.
DITA XML case studiesReal-world structured-authoring solutions.
Document architecture complexityWhen a documentation architecture becomes too complex — and how to recognize it.
Case study: NuFirewall documentationStructured authoring in production, from a press-validated open-source project.

Content reuse

Section titled “Content reuse”
From document to modular documentationMoving from monolithic documents to a modular, reusable content base.

Source vs target formats

Section titled “Source vs target formats”
Source formatChoosing what you write in — the decision that determines your entire toolchain.
Target formatChoosing what you publish to, and why it doesn't have to be the same as your source format.
Formats and toolsWhy the format matters more than the tool — and how to evaluate tooling costs.

Comparing docs-as-code toolchains? See adopting docs-as-code. Looking for Jinja, Sphinx/ReST, or XSL-FOA stylesheet language for transforming and laying out XML content for print/PDF output, commonly paired with DITA XML publishing pipelines.View in glossary → tutorials? See automation & legacy techniques.