Technical writing: process, formats, and tooling

Start from your goal

What are you trying to do?

• Start a documentation project

  Define audience, scope, and deliverables before writing a single word.

  Define the project →

• Build a documentation process

  See the whole production chain, from information gathering to delivery.

  See the process →

• Adopt docs-as-code

  Manage documentation like code: version control, review, and CI/CD.

  Integrate docs with development →

• Choose an authoring model

  Decide how much structure your content needs, from Markdown to DITA.

  Compare the options →

• Improve an existing documentation system

  Audit what you have: orphaned pages, duplicates, and stale content.

  Run an audit →

• Automate documentation

  Build, check, and publish documentation automatically on every change.

  See a CI/CD pipeline →

Guided reading

Six paths through the manual

Read them in order for a complete method, or go straight to the path you need.

1. 01

   Understand documentation

   Why documentation architecture matters: value, maturity, information types.

   Read the foundations →
2. 02

   Build a documentation process

   The workflow step by step, from project definition to delivery.

   Follow the process →
3. 03

   Adopt docs-as-code

   Git, repository design, branches, CI/CD, and automated checks.

   Learn the workflow →
4. 04

   Choose an authoring model

   Structured authoring, DITA, Markdown, content reuse, and formats.

   Compare the models →
5. 05

   Build your toolkit

   Templates, checklists, and worked examples to reuse.

   Open the toolkit →
6. 06

   Automation & legacy techniques

   Jinja, Python, sed, Sphinx/ReST, XSL-FO: specialist and historical techniques.

   Explore the techniques →

Ready to use

Practical resources

Templates, checklists, and worked examples you can copy into your own project.

• Documentation quality checklist

  Run before merging any documentation change.

  Open the checklist →

• Docs-as-code workflow example

  One change, from branch to production, annotated step by step.

  Study the example →

• API documentation template

  One endpoint per page: method, parameters, request/response, error codes.

  Use the template →

• Documentation project plan template

  Goal, audience, scope, format, success criteria, timeline.

  Use the template →

AI assistant

Ask the documentation

Can’t find what you’re looking for? Describe what you need in your own words. Answers are generated from this manual’s content, with links to the pages they drew on. To use the content in your own tools or agents, see this manual’s API.

Ask a question about the documentation

Ask

The assistant answers from the site's documentation only. It does not use general knowledge.

Try an example:

What is DITA XML?How does docs-as-code work?When should I use structured documentation?

Reference

Browse all documentation

Every page in the manual, grouped as in the navigation menu.

1. Understand documentation6 pages

• Overview
• Technical documentation: reduce costs, improve customer satisfaction
• The three levels of technical documentation
• From technical writing to technical communication
• Information types
• KISS Principle of Simplicity

2. Build a documentation process10 pages

• Overview
• Technical writing: an industrial process
• Project definition
• Gathering information
• Testing products to document them
• Content creation
• Validation and quality control
• Translation
• Delivery
• Managing a project from start to finish

3. Adopt docs-as-code11 pages

• Overview
• Integrating documentation into development processes
• Git
  • Version management systems - rustic but reliable
  • Git: from file to content
• Repository design
  • Repository
  • A single repository?
  • Which repository for group work?
  • Shared network directories - unsuitable for group work
  • SQL database
  • CMS: workflow as a bonus, but reliability to be tested
• Using branches in source management systems

4. Choose an authoring model11 pages

• Overview
• Structured authoring
  • Use structured authoring
  • Structured and unstructured formats
• DITA
  • Structured DITA XML format
  • Case studies in using DITA XML
  • Too complex a document architecture?
  • Case study: NuFirewall documentation
• From document to modular document base
• Source vs target formats
  • Source format
  • Target format
  • Formats and tools

5. Build your toolkit18 pages

• Overview
• Templates
  • Template: concept article
  • Template: task article
  • Template: reference article
  • Template: documentation project plan
  • Template: documentation review request
• Checklists
  • Checklist: documentation quality
  • Checklist: technical review
  • Checklist: documentation release readiness
  • Checklist: documentation migration
  • Checklist: docs-as-code adoption
  • Checklist: documentation audit
• Worked examples
  • Example: a well-structured Markdown page
  • Example: a documentation repository structure
  • Example: a basic docs-as-code workflow
  • Example: a documentation review workflow
  • Example: a practical CI/CD pipeline for documentation
• API documentation
  • Template: API documentation

6. Automation & legacy techniques11 pages

• Overview
• Jinja
  • Create different documents from the same sources using Jinja
  • Create different documents from the same sources via Jinja (object method)
  • Automatically insert data into a reStructuredText file
• Python
  • Regular expressions in Python
  • Auto-insert data into a DITA XML file
  • Automatically insert SQL data into a reStructuredText file
• sed: modify your text without opening your files
• Create different documents from the same ReST sources (conditional text)
• DITA XML and XSL-FO tutorials
• The Raspberry Pi 3 as a documentation platform

Explore the reference2 pages

• Explore the reference
• Glossary

Documentation API & AI2 pages

• Documentation API
• Ask the documentation

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.