Technical writing: process, formats, and tooling

Documentation Manual

By Olivier Carrère, technical writer · Opinion Blog ↗

This site is the technical manual: a practical guide to the docs-as-code process, from project definition to delivery. The companion blog publishes in-depth essays, analysis, and opinion.

Whether you're choosing between DITA XML and Markdown, migrating to a docs-as-code workflow, or integrating documentation into a CI/CD pipeline — these guides cover the methods, formats, and tools that make technical documentation a sustainable, scalable engineering practice.

Start Here

A practical path through technical documentation

New to the site or re-evaluating your documentation architecture? Follow this curated sequential path:

01

The three levels of technical documentationLocate where your organization's documentation practice sits today — from ad-hoc drafting to structured DITA.

02

Structured and unstructured formatsThe foundational format choice that determines everything downstream: content reuse, translation cost, and tooling.

03

Case study: NuFirewall documentationStructured authoring in production — a detailed look at the DITA XML techniques that earned press-validated documentation.

04

Integrating documentation into developmentTreating documentation like code: aligning release cadence, version control, automated testing, and CI/CD pipelines.

Technical writing: an industrial process

How to approach technical writing as an engineering discipline - from project definition to version control, automated testing, quality validation, and delivery.

Project definitionDefine audience, scope, and deliverables before writing - five project parameters every technical writing engagement needs.

Integrating documentation into developmentTreat docs like code: same release cadence, same version control, same review process.

Git: from file to contentGit stores content blobs, not filenames - understanding that model makes branching and diffing documentation much simpler.

View all 19 process articles →

Structured DITA XML format

How structured and unstructured documentation differ - topic-based authoring, single-sourcing, and modular document architecture without vendor lock-in.

Case study: NuFirewall documentationPress reviewers cited the documentation as a product strength, not a supplement. A detailed look at the DITA XML techniques that made it possible.

Structured and unstructured formatsDITA's three topic types - concept, task, reference - enforce structure that makes content reusable, translatable, and consistent.

From document to modular document baseReplace monolithic manuals with reusable topic modules: lower translation costs, parallel reviews, multiple output formats from one source pool.

View all 5 formats articles →

The business case for structured documentation

Why documentation architecture matters to an organization - maturity models, long-term maintenance costs, and technical communication economics.

From technical writing to technical communicationTechnical communication starts before the sale - why the role spans marketing, journalism, and product documentation.

The three levels of technical documentationA three-tier maturity model - wasteland, topic-based, structured DITA - to locate where your organization sits and what the next level costs.

Formats and toolsChoose your source format before your tool - the format determines vendor lock-in, automation options, and long-term costs.

View all 5 strategy & economics articles →

Tutorials

Practical implementation guides and tooling - step-by-step instructions for DITA-OT, XSL-FO, Sphinx, Python regular expressions, and automation scripts.

DITA XML and XSL-FO tutorialsSet up the DITA XML to PDF publishing chain with XSL-FO - step-by-step from source authoring to styled output.

Conditional text with SphinxGenerate document variants from the same ReST sources with Sphinx conditional text.

Regular expressions in PythonPython's regular expression library helps you manipulate text, especially if you're not familiar with sed or awk.

View all 11 tutorials →

Browse All

Browse the full documentation manual

40 articles covering the full spectrum of technical communication, from foundational strategy to automated publishing pipelines.

Industrial Process19 articles

Definition, Git, branching, validation, translation, delivery

Explore section →

Structured DITA XML5 articles

DITA XML, modularity, case studies, and document architecture

Explore section →

Business Case & Strategy5 articles

Maturity tiers, tooling costs, KISS principle, and documentation ROI

Explore section →

Practical Tutorials11 articles

DITA-OT, XSL-FO, Sphinx, Python regex, and publishing pipelines

Explore section →