Technical writing: process, formats, and tooling
Methods, formats, and tooling for technical writers who treat documentation as an engineering practice.
A practical guide to the docs-as-code process, from project definition to delivery - the blog is essays and opinion; this is the manual.
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 organization’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 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.
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 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.
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 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.
Explore all 5 articles →KISS principle, PDF indexes, and the business case for structured documentation.
Tutorials
Section titled “Tutorials”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.
Explore all 11 articles →Jinja templating, SQL automation, sed, and documentation toolchains.