Technical writing: process, formats, and tooling

An engineering approach to designing, writing, maintaining, and publishing technical documentation.

Start with the process Browse all documentation Get in touch

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.

AI Assistant

Ask the documentation

Have a specific question about technical writing, DITA XML, content reuse, or version control? Ask our AI assistant, grounded strictly in this site’s documentation.

Try an example:

Start Here

A practical path through technical documentation

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

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

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

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

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

Learn technical writing

Foundational principles, terminology, and audience-first thinking - start here if you’re new to the practice, or want a refresher.

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

The KISS principleWhy the simplest solution that solves the problem beats the cleverest one.

Structured and unstructured formatsThe foundational format choice that determines reuse, translation cost, and tooling.

Learn technical writing

Build a documentation process

How to approach technical writing as an engineering discipline - from project definition to quality validation and delivery.

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

Content creationTurning gathered information into structured, usable content.

DeliveryGetting finished documentation to the people who need it, in the format they need it in.

Build a documentation process

Adopt docs-as-code

Treat docs like code - same release cadence, same version control, same review process, same CI/CD pipeline.

Integrating documentation into developmentAligning release cadence, version control, automated testing, and CI/CD pipelines.

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

sed: modify your text without opening your filesBatch find-and-replace across hundreds of files in one command.

Adopt docs-as-code

Use structured authoring

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.

Use structured authoring

Choose tools and formats

The decisions that shape everything else - source format, target format, and which tools actually pay for themselves.

Source formatChoosing what you write in - the decision that determines your entire toolchain.

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

Is an index useful in a PDF?A concrete example of a format-driven trade-off decision.

Choose tools and formats

Browse All

Browse all documentation

Already know what you’re looking for? Seven goal-based paths cover the full spectrum of technical documentation, from foundations to a ready-to-use toolkit.

Learn technical writing

Principles, terminology, audience analysis, and task-based writing.

Explore →

Build a documentation process

Planning, authoring, review, governance, and maintenance.

Explore →

Adopt docs-as-code

Git, Markdown, pull requests, CI/CD, and static publishing.

Explore →

Use structured authoring

DITA, information typing, reuse, and content models.

Explore →