Skip to content
Olivier CarrèreTechnical writing practice

Understand documentation

Foundational principles, terminology, and audience-first thinking for anyone starting out in technical writing — or refining their practice.

1 min read

View as Markdown

Start here if you’re new to technical writing, or want a refresher on the principles behind everything else in this manual: why documentation is worth investing in, where documentation maturity comes from, how technical writing relates to Technical communicationThe broader discipline that spans the entire product life cycle and reaches general audiences, prospects, and journalists — as distinct from technical writing, which produces user-facing product documentation after a sale.View in glossary →, and how Information typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary → structure content.

Business case & strategy overviewMaturity tiers, tooling costs, and documentation ROI — the argument for investing in a better process.
The three levels of technical documentationLocate where your organization's documentation practice sits today — from ad-hoc drafting to structured DITA.
From technical writing to technical communicationHow the discipline differs from marketing and general copywriting, and why that distinction matters for process design.
Information typesThe architectural foundation: Concepts, Tasks, and References, their relationship to DITA, and how they shape our authoring templates.
The KISS principleWhy the simplest solution that solves the problem beats the cleverest one, and how that applies to documentation.

How the rest of this manual builds on them

Section titled “How the rest of this manual builds on them”

The sections that follow form a progression. Documentation is only as maintainable as its structure, so structured information and modular content come first. Modular text sources can be managed in Git like code, which makes automation and CI/CD possible. Content that is structured and built automatically can then also be published in machine-readable form, for scripts, search systems, and AI assistants as well as human readers.

Once these foundations click, move on to building a documentation process or jump straight to the practical toolkit for templates and checklists. For the foundational format choice, see choosing an authoring model. For unfamiliar terms, see the glossary.