Technical Writing & Documentation Exercises

Diataxis is a documentation structure created by Daniele Procida that divides all documentation into four types: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). Each type serves a different user need. Technical writers use Diataxis to diagnose documentation gaps and organise content so users can find what they need quickly. The framework has been widely adopted by major open-source projects including Django and Linux kernel documentation.

Plain language means writing that the reader can understand the first time they read it. In technical writing, plain language principles include: using active voice, choosing common words over jargon where possible, writing short sentences, structuring content with the most important information first, and using numbered lists for sequential steps. The UK government's GOV.UK style guide and US Plain Writing Act both mandate plain language for public-facing content.

Docs as code is the practice of writing and managing documentation using the same tools and workflows as software code: version control (Git), pull requests, automated testing (link checkers, linters), and CI/CD pipelines. Key vocabulary: Markdown or AsciiDoc (lightweight markup languages), static site generators (MkDocs, Docusaurus, Hugo), content linting, and docs deployment pipeline. It enables developers to contribute to documentation using familiar workflows.

API documentation vocabulary includes: endpoint (a specific URL path), request/response (what the client sends and what the server returns), parameters (path, query, header, and body parameters), authentication schemes (API key, OAuth 2.0, Bearer token), status codes (200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error), rate limiting, pagination, and code samples. OpenAPI (Swagger) specification vocabulary is also essential for describing REST APIs formally.

A style guide is a set of standards for writing and formatting documentation. It covers word choice, tone, punctuation, heading capitalisation, code formatting, and terminology. Common technical writing style guides include: Google Developer Documentation Style Guide (widely used for developer docs), Microsoft Writing Style Guide, Apple Style Guide, and the Chicago Manual of Style. Most organisations also maintain an internal style guide for product-specific terminology.

In the Diataxis framework, a tutorial takes a complete beginner through a learning experience — the goal is learning, not completing a real task. A how-to guide helps an experienced user accomplish a specific real-world task — the goal is completing the task, not teaching. Example: "Getting started with the API" is a tutorial; "How to authenticate with OAuth 2.0" is a how-to guide. Mixing these types in one document is a common documentation anti-pattern that confuses readers.

Information architecture (IA) in documentation refers to how content is organised, labelled, and navigated. Good IA means users can predict where to find information and the navigation labels match their mental model. Technical writers discuss IA using terms like: taxonomy (category structure), navigation hierarchy, content model (the template structure for each content type), and progressive disclosure (showing basic information first with details available on demand).

Single-sourcing means writing content once and reusing it in multiple outputs or contexts — for example, the same warning note appearing in both a web guide and a PDF export. Tools like MadCap Flare, DITA (Darwin Information Typing Architecture), and reStructuredText with Sphinx support single-sourcing through includes, variables, and conditional text. Technical writers use single-sourcing to reduce maintenance burden when the same information must appear in multiple documents.

A technical writer translates complex technical information into clear, accurate documentation for a specific audience. In an engineering team you might say: "The technical writer owns the docs site, works with engineers to review accuracy, applies the style guide for consistency, and is responsible for the documentation strategy — including deciding what to document and how to structure it." Technical writers often also manage the docs toolchain and contribute to content strategy for developer portals.

Content debt (analogous to technical debt) is the accumulation of outdated, inaccurate, duplicated, or missing documentation that degrades the user experience over time. It builds up when products change faster than documentation is updated. Technical writers discuss content debt in audits: "We have significant content debt in the authentication section — three of the five OAuth guides describe flows that no longer exist." Addressing content debt typically involves a documentation audit, archiving obsolete pages, and a content refresh sprint.