Technical writing: process, formats, and tooling
Methods, formats, and tooling for technical writers who treat documentation as an engineering practice.
Whether you’re choosing between DITA XML and Markdown, moving 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 practice.
New here? Start with these four articles
Section titled “New here? Start with these four articles”- The three levels of technical documentation — locate where your organisation’s documentation practice sits today
- Structured and unstructured formats — the format choice that determines everything downstream
- Case study: NuFirewall documentation — structured authoring in production, with a press-validated outcome
- Integrating documentation into development — the workflow and toolchain change that follows
Technical writing: an industrial process
Section titled “Technical writing: an industrial process” Project definition Define audience, scope, and deliverables before writing — five project parameters every technical writing engagement needs.
Integrating documentation into development Treat docs like code: same release cadence, same version control, same review process.
Git: from file to content Git stores content blobs, not filenames — understanding that model makes branching and diffing documentation much simpler.
Explore all 19 articles → Source formats, repositories, version control, translation, delivery, and more.
Structured DITA XML format
Section titled “Structured DITA XML format” Case study: NuFirewall documentation Press 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 formats DITA's three topic types — concept, task, reference — enforce structure that makes content reusable, translatable, and consistent.
From document to modular document base Replace monolithic manuals with reusable topic modules: lower translation costs, parallel reviews, multiple output formats from one source pool.
Explore all 5 articles → Structured formats, DITA XML use cases, and document architecture trade-offs.
The business case for structured documentation
Section titled “The business case for structured documentation” From technical writing to technical communication Technical communication starts before the sale — why the role spans marketing, journalism, and product documentation.
The three levels of technical documentation A three-tier maturity model — wasteland, topic-based, structured DITA — to locate where your organisation sits and what the next level costs.
Formats and tools Choose your source format before your tool — the format determines vendor lock-in, automation options, and long-term costs.
Explore all 5 articles → KISS principle, PDF indexes, and the business case for structured documentation.
Tutorials
Section titled “Tutorials” DITA XML and XSL-FO tutorials Set up the DITA XML to PDF publishing chain with XSL-FO — step-by-step from source authoring to styled output.
Conditional text with Sphinx Generate document variants from the same ReST sources with Sphinx conditional text.
Regular expressions in Python Python's regular expression library helps you manipulate text, especially if you're not familiar with sed or awk.
Explore all 11 articles → Jinja templating, SQL automation, sed, and documentation toolchains.