Skip to content
Olivier CarrèreTechnical writing practice

Use structured authoring

DITA XML, information typing, content reuse, and modular content models — with real-world case studies.

1 min read

View as Markdown

The discipline of Information typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary →: splitting content into concepts, tasks, and reference material that can be reused and assembled into different deliverables. DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → is the most formal implementation of these principles and the one this section documents in depth; the same principles can be applied with lighter formats, as the information types page and the toolkit templates show.

Formats and architecture

Section titled “Formats and architecture”
Information typesConcept, task, and reference: the typing that structured authoring is built on, in DITA or in Markdown.
Structured vs. unstructured formatsThe foundational choice that determines reuse, translation cost, and tooling.
DITA XML case studiesReal-world structured-authoring solutions.
Document architecture complexityWhen a documentation architecture becomes too complex — and how to recognize it.
From document to modular documentationMoving from monolithic documents to a modular, reusable content base.
Case study: NuFirewall documentationStructured authoring in production, from a press-validated open-source project.

Tutorials

Section titled “Tutorials”
DITA XML and XSL-FO tutorialsAuthoring in DITA XML and generating PDF output with XSL-FO style sheets.
Auto-insert data into a DITA XML fileDynamically insert product data into DITA topics.
Conditional text with Jinja (object method)Define audience, platform, and version as Python objects, then filter content at build time.
Conditional text with JinjaA Python preprocessing script that includes or strips content sections before generation.
Conditional text with Sphinx/ReSTGenerate document variants from the same ReST sources.
Auto-insert data into a reStructuredText fileTemplate a ReST file so Python fills in product names and versions at build time.
Auto-insert SQL data into a reStructuredText fileQuery a product database and render results directly into documentation.

Deciding between DITA and 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 the first place? See choosing an authoring model.