Case studies in using DITA XML

Practical DITA XML solutions and tips developed through daily multilingual technical writing projects - structured authoring, topic reuse, conditional text, and publishing.

Updated September 2026, 1 min read

View as Markdown

My daily use of the DITA XML structured authoring format on multilingual projects as a technical writer has enabled me to develop several solutions and tips, which I’d like to share with you here. We welcome any feedback you may have!

The NuFirewall documentation

Documented: NuFirewall, a software product. Its documentation, developed using DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary →, was praised by the press as a notable strength of the product.
Techniques illustrated: Reusing information blocks with ConrefA DITA XML mechanism for reusing a block of content by reference: the content of a target node is replaced by the content of a source node at compile time.View in glossary →: centralizing them, choosing the lowest-level XML node, translation constraints, limits on nesting, and protecting confidential information. Providing targeted information with DitavalA DITA XML filter file that includes or excludes content marked with matching attributes at compile time — the mechanism behind DITA's conditional text.View in glossary → Conditional textContent marked as applying only to a given audience, product version, or output, so that one source can be filtered at build time into different deliverables. DITA XML implements it with ditaval files; template engines such as Jinja do the same for text formats.View in glossary →.
Read it to: See how these reuse and filtering decisions were made on the documentation of a real product.

Case study: NuFirewall documentationConref strategies and Ditaval conditional text, with diagrams for each decision.

Solutions and tips from multilingual projects

The DITA XML and 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 collect the procedures that came out of this daily use, for example:

Managing multilingual projects. A methodology and a Bash script that generate each language version from a single DitamapAn external table-of-contents file that assembles DITA XML topics into a document, without the topics themselves needing to know their position in that document.View in glossary → file.
Conditional text. Different documents from the same DITA sources, filtered with ditaval files.
PDF output. Adjustments to DITA-OT (DITA Open Toolkit)The open-source publishing engine that transforms DITA XML sources, assembled by a ditamap, into target formats such as PDF (via XSL-FO) and HTML.View in glossary → and XSL-FO style sheets, such as displaying cross-references.

DITA XML and XSL-FO tutorialsAll the tutorials, grouped by task: publishing a first PDF, creating several documents from the same sources, customizing PDF output, and editing in Emacs.

Lessons on complexity and translation

Too complex a document architecture? The levels of complexity DITA XML introduces, and the solutions that help manage them.
Using branches in source management systems. Managing translations across multiple language branches requires careful planning.

From document to modular document base

From DITA XML to Markdown: lightweight information typing - carrying these DITA lessons over to a 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 → workflow.