Technical writing

Documentation written from the product, not from the spec

Most bad documentation was written from a requirements document or a developer's memory. It describes how the feature was meant to work, not the screen the user actually sees, with its renamed button and its extra confirmation step. The user follows step four, finds nothing matching, and opens a ticket.

We perform every procedure in the product before writing it, on a test account, in the role the reader will have. Where a step behaves differently from what the team expects, we log it, because documentation work routinely surfaces bugs nobody had reported. That list often turns out to be as valuable as the docs.

Separate the task from the explanation

A user trying to export an invoice does not want three paragraphs on the billing model first. A user trying to understand the billing model does not want a numbered list of clicks. Mixing the two in one article makes both harder to find and slower to read.

We split content into tasks (how to do one thing), concepts (how something works and why) and reference (settings, fields, limits, error codes). Each type has its own template, so pages stay consistent after we hand over and your team adds the fortieth article.

The terminology list is what keeps the set coherent over time. If the interface says 'workspace', the documentation never says 'project' or 'account' for the same thing. It is a small document that prevents most of the confusion users report.

• Task articles: one goal, numbered steps, the result the user should see
• Concept articles: the model behind a feature, with a diagram where it helps
• Reference pages: every field, setting and limit, in a scannable table
• Troubleshooting: the error message as written, its cause and the fix