Ten Rules for High-Quality Technical Documentation

Technical documentation helps people use, understand, configure, or troubleshoot a product or service. A page works well when it serves a specific reader and purpose, explains what that reader needs to know, and makes the expected result clear. These ten rules help you plan, write, check, and maintain technical content.

Use these rules as a checklist while planning, drafting, and reviewing a page.

1. Start with a reader and a task

Before drafting, identify who will use the page and what they need to do or understand. A user need is a specific goal, such as setting up an integration or understanding how a permission works. Base that need on evidence, such as user research, support questions, or product analytics, rather than assumptions about what readers know. Google’s audience guidance recommends accounting for readers’ roles and how familiar they are with the subject, along with their prerequisites; the Office for National Statistics likewise advises basing content on evidence about users.

A planning sentence is: “For [reader], this page helps them [task or learning goal], assuming [prerequisites].” If you cannot fill in those parts, clarify the page’s purpose before writing. Use the sentence to decide what belongs on the page and what readers can find elsewhere.

2. Choose a form that fits the reader’s goal

A page should teach, direct, explain, or provide facts according to the reader’s need. The Diátaxis framework names four useful forms: a tutorial teaches through guided practice; a how-to guide helps someone complete a task; reference material provides facts to look up; and an explanation builds understanding of a concept or design choice.

Choose the form before outlining. For example, a setup page should focus on the ordered actions needed to reach a working setup. Put detailed parameter definitions in reference material and link to them rather than interrupting the setup with a long catalog. Related pages can serve different needs without forcing one page to do every job.

3. State prerequisites, scope, and limits early

Tell readers which product, version, role, or environment the instructions cover. Describe prerequisites so readers can tell whether they meet them. “You need access to the service’s administrative settings” gives a clearer boundary than “for advanced users.” Google’s document guidance recommends identifying the intended audience and relevant assumed knowledge.

Put conditions near the instructions they affect. If a procedure applies only to a particular product version, name that version before the steps. If readers need permissions or a separate tool, say so before they begin. Stating the scope early lets readers see whether the page matches their situation and what they need before starting.

4. Organize the page so readers can find an answer

Use a descriptive title and headings that summarize the section below them. Break up long pages so readers can scan for what they need, whether that is a task, a setting, or an explanation. On pages longer than a few paragraphs, clear subheadings help readers understand the structure and go straight to relevant sections, as W3C’s writing guidance explains.

Use numbered steps when readers must act in order, and bullets when order does not matter. In a web page, mark headings as actual headings rather than merely making text bold or large. A semantic heading is a heading identified in the page’s underlying structure, so browsers and assistive technologies can recognize the outline and move through it.

5. Use consistent words and make the actor clear

Choose one term for each product feature or action, then use it consistently. If a term is unfamiliar or has a specific meaning in your product, explain it the first time it appears. Prefer familiar words when they preserve technical accuracy, and keep necessary technical detail when a simpler substitute would be vague. Google’s audience guidance recommends matching language to reader knowledge and explaining unfamiliar terms.

Name the person, service, or component that performs an action. “The client sends the request” tells readers who acts; “the request is sent” leaves the actor unstated. Active voice usually makes responsibility clearer. As Google’s style guidance notes, passive voice also works when the actor does not matter or the affected object deserves emphasis.

6. Write procedures readers can follow and verify

Give steps in the order readers should perform them. State prerequisites before the first action, and place warnings or conditions before the step they affect. Then describe what readers should see or check after the action. For example, a procedure can name the setting to change and explain which status or output confirms that the change took effect. The exact check should match the product’s documented behavior.

A vague instruction such as “Configure the connection” leaves readers to guess what to change and how to confirm success. Name the required action, the relevant setting, and the expected result. Google’s editing guidance recommends clear, ordered instructions and placing conditions before the steps they qualify.

7. Test examples and code before publishing

Readers treat code samples as something they can copy and run. Test each sample against the product or language version named on the page, and make sure it performs the stated task. Explain any required setup, dependencies (other components the sample needs), and placeholders so readers know what to replace. When the output helps them verify success, show the expected result. Google’s guidance on creating sample code emphasizes working examples and enough context to use them correctly.

Keep examples focused, but do not shorten them by removing details needed for correctness or safe use. A sample that looks concise but fails when copied sends readers into debugging work that the documentation should have prevented. Recheck samples after changes to the product or supported version, and whenever the surrounding instructions change.

8. Build accessibility into the page

For web documentation, use descriptive link text, meaningful headings, and text descriptions for informative images or diagrams. “Read the API authentication instructions” tells readers what a link opens; “click here” does not. Check the rendered page, since source text alone does not show whether headings, links, and images work as readers encounter them.

The Web Content Accessibility Guidelines (WCAG) 2.2 set testable requirements for web content. These include criteria for text alternatives and page titles. Other criteria address link purpose, headings, and labels. Following a few writing tips does not by itself show that a page meets WCAG requirements. Apply the relevant criteria to the web content and conformance level you need to assess.

9. Review facts, usability, and presentation separately

A grammar check cannot confirm that a command works or that a procedure matches the current product. Ask reviewers to examine distinct questions: Does the technical content match the product? Can the intended reader follow the page? Does the wording follow the publication’s style? Does the rendered page preserve its headings, links, and layout? Reviewing these questions separately makes it easier to catch problems that one review can miss.

For documentation stored in a repository, review proposed changes alongside the product changes they describe. GitHub’s contribution guidance includes checks to confirm technical accuracy and versioning, plus previews of the rendered page. Adapt those checks to your publishing setup rather than treating one organization’s review process as a universal requirement.

10. Revisit pages when the product changes

A page becomes unreliable when its instructions describe an older interface, behavior, or supported version. Assign an owner or a clear review trigger to important pages, such as a change to the feature they document. For versioned documentation, which keeps separate content for each product version, check that each page points readers to instructions and examples for the version they use.

Use support questions, analytics, and user feedback to identify pages worth reviewing. Treat those signals as clues, then check the page against the product and the reader’s task. The Diátaxis guidance on maintaining documentation frames documentation as work that continues to adapt as products and users change.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com