TS-24: User manuals

This technical standard covers documentation written for the people who use a software product to get something done — end users, not developers. It applies to help centers, in-product help, onboarding guides, and any other material that explains how to operate the product rather than how it is built.

This is a narrower concern than technical documentation in general. For documentation aimed at engineers, operators, and other contributors — READMEs, API references, architecture docs, runbooks — see TS-25: Technical documentation, whose section on UX writing also covers the words that appear inside the product itself — button labels, error messages, empty states. A user manual is the material a reader seeks out deliberately, in addition to that in-context UI text. For sentence-level writing conventions that apply to any document, technical or otherwise, see TS-26: Technical writing style guide.

Scope

A user manual explains how to use a finished product. Its reader is not a developer, and often has no interest in how the product works internally — they want to accomplish a task and move on.

This standard applies to any documentation written primarily for that reader: a help center, an in-product help panel, a printed or PDF manual, an onboarding email sequence, a "Getting started" guide. It does not apply to documentation aimed at people who build, operate, or extend the product — that is TS-25: Technical documentation's territory.

The distinction is the reader, not the format or the channel. A guide titled "API reference" that is actually written for the developers integrating against the API is technical documentation, even though it ships alongside end-user help content and uses the same publishing pipeline. Conversely, a short in-app tour aimed at a non-technical end user is user documentation, even though it might live in the same repository as the code it documents.

Some products have no meaningful gap between these two audiences — an internal admin tool used only by the engineers who built it, for example. This standard does not apply where a product genuinely has no end-user audience distinct from its developers. It also does not apply retroactively to every product on principle: a simple product with a self-explanatory interface may need no user manual at all. Writing one because a standard exists is not a goal in itself — see When not to write a user manual.

Audience

Unlike a document written for a fellow engineer, a user manual usually cannot assume its reader shares the author’s vocabulary, mental model, or tolerance for ambiguity. Before writing, establish what the reader already knows and what they are trying to do.

Segment by task, not by role

Technical documentation often segments its audience by role — maintainer, consumer, operator (see TS-25: Technical documentation's section on audience). User manuals SHOULD instead segment by the task the reader is trying to complete, because end users of the same product commonly share a role ("customer", "member", "user") but arrive with very different goals: one reader wants to set up the product for the first time, another wants to fix something that broke, another wants to accomplish an advanced task they have done before but forgotten the steps for.

Structuring a manual by feature or by menu hierarchy mirrors how the product was built, not how the reader thinks about their problem. A reader who wants to "export my data before canceling" should not have to know that the export function lives under Settings > Account > Advanced to find the right page.

Assume less than you think

The reader of a user manual is frequently:

• Using the product for the first time, or returning to a rarely-used feature they have forgotten.
• Not a native speaker of the language the manual is written in.
• Frustrated, because the most common reason to open a help page is that something did not work as expected.
• Reading on a small screen, or listening via a screen reader, rather than reading a full page on a desktop monitor.

Write for the least context-rich version of this reader. A step that seems obvious to someone who built the product ("open the settings panel") may not be obvious to someone encountering the interface for the first time — name where the control is, not just what to do with it.

When not to write a user manual

Not every product needs one. A well-designed interface that follows established conventions and provides its own in-context guidance (see In-product help versus standalone manuals) may need no separate manual at all — every additional page is one more thing that can go stale. Write a user manual where the product has genuine complexity, an unavoidable learning curve, or actions with consequences serious enough to warrant a considered explanation before the reader commits to them (a permanent deletion, a paid plan change). Do not write one merely because a policy says every product must have one; a manual whose main content is a restatement of what the interface already makes obvious offers false reassurance rather than help.

Structure

A user manual SHOULD be organized around a small number of predictable content types, so a returning reader learns where to look once and can reuse that knowledge across the rest of the manual.

The core content types

• Getting started. A short path from "I have just signed up" to "I have done the one thing that proves this product works for me." This is not a table of contents in disguise — it is a curated subset of the product’s capabilities, deliberately narrow.
• Task-based guides. Step-by-step instructions for a single, named task ("Invite a teammate", "Cancel a subscription"). See Task-based writing for how these are written.
• Conceptual overviews. Short explanations of a concept the reader needs before a task makes sense (what a "workspace" is, how billing periods work). Kept separate from task guides so a returning reader who already understands the concept can skip straight to the steps.
• Reference material. Exhaustive listings — keyboard shortcuts, field definitions, permission levels, plan comparisons — that a reader consults rather than reads start to finish.
• Troubleshooting and FAQs. Answers to specific failure modes and recurring questions. See Troubleshooting and FAQs.

Mixing these within a single page is the most common structural failure: a task guide that digresses into conceptual explanation forces every reader, including the one who already understands the concept, to scroll past it to find the steps.

Findability

A manual’s structure only helps the reader if they can locate the right page. At minimum, provide:

• A search function, if the manual has more than a handful of pages. Most readers arrive at a specific page from search, not from browsing a table of contents.
• A small number of top-level categories, grouped by the reader’s goals rather than the product’s internal module boundaries.
• Cross-links between related pages — a task guide that depends on a concept SHOULD link to that concept’s page rather than re-explaining it inline.

Where the manual is large enough to need it, categories SHOULD map onto distinct reader goals ("Getting started", "Billing", "Troubleshooting") rather than onto engineering subsystems, which rarely mean anything to the reader.

Task-based writing

Most user-manual content that gets read to completion is a task guide: a reader arrived with a specific goal and wants the shortest reliable path to it. Task guides SHOULD be written to that goal, not to the product’s feature set.

Title the task, not the feature

A task guide’s title SHOULD name the outcome the reader wants ("Export your data", "Reset a forgotten password"), not the UI element that performs it ("Using the export panel"). The reader searches for what they want to happen, not for the name of a button.

Lead with the steps

State any genuinely necessary context first, in one or two sentences, then move directly into numbered steps. Background the reader does not need to complete the task — why the feature exists, how it is implemented, its full history — belongs in a conceptual overview the guide can link to, not inline before the steps.

== Export your data

You can export all of your data as a ZIP file at any time. The export
includes everything in your account except billing history.

1. Open *Settings > Account*.
2. Select *Export data*.
3. Choose a format, then select *Start export*.
4. Wait for the confirmation email — large accounts can take up to an hour.

One outcome per guide

A task guide SHOULD cover exactly one outcome. A guide that tries to cover several related tasks under one title ("Managing your account") forces every reader to scan past steps for tasks they are not performing. Split by outcome instead, and link the related guides to each other.

Write steps as actions

Each step SHOULD be a single, concrete action, using an imperative verb at the start: "Select", "Open", "Enter" — not "You should select" or "The user selects." State where the control is if its location is not obvious from the previous step, and state what the reader should see happen, where that confirms they are on the right path.

Cover the fork in the road

Where a task branches — different steps for a free plan versus a paid plan, for instance — say so explicitly at the point where the paths diverge, rather than writing one guide that silently assumes one branch and leaving the other reader stranded partway through.

In-product help versus standalone manuals

User documentation reaches the reader through two distinct channels, and a mature product needs both. Neither substitutes for the other.

In-product help

Tooltips, inline hints, empty-state guidance, and contextual help panels appear at the point of use, when the reader is already looking at the relevant part of the interface. This is the cheapest moment to reach a reader, because it requires no navigation away from their task, but it is also the most space-constrained — a tooltip has room for a sentence, not a procedure.

In-product help SHOULD cover the small decisions a reader makes in the moment: what a specific field means, what a specific toggle does, what will happen if they proceed. See TS-25: Technical documentation's section on UX writing for the conventions that govern this text specifically.

Standalone manuals

A help center, PDF manual, or dedicated documentation site serves the reader who needs more than a sentence: a multi-step procedure, background context, or material they want to consult before starting rather than mid-task. It is also the channel a reader reaches through search, from outside the product entirely — before they have signed up, or while troubleshooting an issue that is preventing them from opening the product at all.

Linking the two

The two channels SHOULD be linked, not maintained as separate, disconnected bodies of content. In-product help SHOULD link out to the relevant standalone guide where a task is too long to explain in place. A standalone task guide that documents a multi-step flow SHOULD note, where relevant, what in-product help is available at each step, so the two channels reinforce rather than duplicate each other.

Duplicating full procedural content in both places is a maintenance liability — a step that changes in the product now has to be updated in two places, and one is easy to miss. Prefer a short in-product hint with a link to the canonical standalone version over maintaining the same procedure twice.

Visuals

A user manual’s reader is usually looking at the product’s interface at the same time as the manual. Screenshots, annotated diagrams, and short screen recordings let the reader match what they see against what the manual describes, which is often faster than parsing a purely textual description of a visual layout.

When a screenshot earns its place

Include a screenshot where the reader has to locate something in a complex or unfamiliar interface, or where an annotation (an arrow, a highlighted region) communicates faster than a sentence would. Do not include a screenshot of every single step in a simple, linear procedure — a wall of near-identical images slows the reader down and multiplies the maintenance burden with no benefit past the first one or two steps.

Keep screenshots current

A screenshot is a snapshot of the interface at a point in time, and the interface changes more often than the manual is likely to be reviewed. An outdated screenshot actively misleads the reader, who trusts what they see over what the text says when the two disagree. Where practical:

• Prefer capturing UI regions likely to stay stable (a settings panel) over regions that change frequently (a dashboard with live, evolving content).
• Crop tightly to the relevant region rather than capturing the full window, so a redesign of unrelated chrome does not force a re-capture.
• Treat a screenshot as a candidate for review at the same time as the procedure it illustrates — see Versioning and maintenance.

Accessibility

Every screenshot and diagram MUST have alternative text conveying the information a sighted reader would get from it, per TS-25: Technical documentation's section on accessibility. In a user manual specifically, this means describing what the reader needs to do or notice, not just labeling the image ("The Export data button, in the Settings > Account panel," not "Screenshot of settings screen").

Video and screen recordings

A short screen recording can communicate a fast sequence of UI interactions more efficiently than a series of static screenshots, particularly for motion-dependent actions like drag-and-drop. Keep recordings short and narrowly scoped to one task. A recording MUST be accompanied by an equivalent text version of the same procedure — captions and a transcript at minimum — so the content remains accessible to readers who cannot or do not want to watch a video, and so the content remains searchable.

Troubleshooting and FAQs

Troubleshooting content and FAQs serve a reader who has already hit a problem, which makes them the highest-stakes pages in a user manual: the reader is more likely to be frustrated, and more likely to give up on the product entirely if the page does not resolve their issue.

Organize by symptom, not by cause

A reader troubleshooting a problem knows what they are observing, not what is causing it. Title and structure troubleshooting entries around the symptom ("Upload stuck at 0%", "Can’t log in after password reset"), and let the entry itself walk through possible causes and their fixes — do not require the reader to already know the underlying cause to find the right entry.

Give a fix, not just a diagnosis

An entry that correctly identifies why a problem happens but stops short of what to do about it leaves the reader no better off. Every troubleshooting entry SHOULD end in an action the reader can take: a setting to change, a step to retry, or a clear statement of who to contact and what information to provide if the entry cannot resolve it themselves.

FAQs are not a dumping ground

A "Frequently Asked Questions" page SHOULD contain questions that are actually asked frequently — verified against real support volume where that data is available (see Feedback and metrics) — not every question the author can imagine a reader having. An FAQ that mixes genuinely common questions with rare edge cases makes the common ones harder to find, and undermines the reader’s trust that the page reflects real usage.

Prefer promoting a genuinely common question into its own task guide or conceptual page, linked from the FAQ, over letting the FAQ grow into a disorganized secondary manual. See TS-25: Technical documentation's section on support-driven documentation for how recurring support questions feed back into documentation more broadly — the same feedback loop applies here, with the FAQ and troubleshooting pages as its primary destination.

Versioning and maintenance

A user manual describes a moving target. Unlike a reference document that can be regenerated from source, most user-manual content is hand-written prose that has no automatic signal telling its author when the product has moved past it.

Tie manual updates to release process

A change that alters a documented flow — a renamed setting, a moved menu item, a changed default — SHOULD update the corresponding manual page as part of the same change, not as a follow-up ticket that competes with the next release for priority. Where the team maintaining the product is different from the team maintaining the manual, the release process SHOULD include a checkpoint that surfaces user-facing changes to whoever owns the manual.

Version-specific content

Where a product is available in materially different versions at the same time — old and new plans, a legacy and a redesigned interface, multiple major versions of a self-hosted product — the manual MUST make clear which version each page describes, and SHOULD avoid silently mixing content from different versions on the same page. A reader on an old interface following a guide written for the new one will not recognize the controls being described and has no way to know the mismatch is the reason.

Retire, don’t just add

Manuals accumulate pages faster than they shed them, because writing a new page is a natural byproduct of shipping a new feature, while removing an obsolete page requires someone to notice it is obsolete. Deprecating or removing a feature SHOULD include removing or clearly marking the corresponding manual page as outdated, in the same way removing a code path should include removing its dead documentation. A stale page that ranks in search above the current one actively misdirects the reader.

Review cadence

Where a manual has no natural trigger tying it to code changes — a conceptual overview, a getting-started guide — it SHOULD still be reviewed on a periodic cadence, because product behavior drifts even where no single change was large enough to prompt an update. An annual review is a reasonable default for stable, low-traffic pages; high-traffic pages (see Feedback and metrics) warrant more frequent review.

Localization

A user manual reaches a broader and less technical audience than most technical documentation, which makes localization a more common requirement for it than for developer-facing docs, where English is a de facto lingua franca.

Write source content to translate cleanly

Where a manual is translated into other languages, the source content SHOULD be written to make translation easier and cheaper:

• Prefer short, simple sentences over long ones with multiple clauses — they are less likely to be mistranslated and easier to machine-translate accurately as a starting draft.
• Avoid idioms, culturally specific references, and humor that assumes shared cultural context. "Under the hood" or "a piece of cake" do not translate literally and may confuse a translator working from a bilingual dictionary.
• Use consistent terminology for the same concept throughout. Varying the word used for the same UI element ("workspace" in one place, "project" in another) forces a translator to guess whether the variation is meaningful.
• Keep UI element names in screenshots and inline text consistent with the actual localized product where the reader’s locale is known — a translated manual that references an English button label the reader will never see is actively unusable.

Structural considerations

Text length varies significantly between languages — German and Finnish text commonly run 20-30% longer than the equivalent English, for example. Layouts built around English text length (fixed-width callout boxes, screenshots with overlaid English captions) SHOULD accommodate this variance rather than truncating or overflowing in translation.

What to localize first

Where full localization of an entire manual is not feasible, prioritize the content the widest audience needs most: getting-started material and the most common troubleshooting entries (see Feedback and metrics for identifying these) over exhaustive reference material, which a motivated reader can more readily work through even in a non-native language.

Feedback and metrics

A user manual’s authors are rarely its readers, and rarely encounter the product for the first time the way its readers do. Direct feedback and usage data are the correction mechanism for the gap between how the manual reads to its author and how it reads to an actual reader.

Page-level feedback

A lightweight feedback prompt on each page — "Was this helpful?", with an optional free-text follow-up — is a low-cost way to surface pages that are failing their reader, even without a large support team. Treat a consistently low helpfulness score as a signal to review the page, not as a metric to optimize directly; a confusing question can produce a low score even on a well-written page, so the free-text responses matter more than the raw number.

Usage data

Where available, page views, search queries with no results, and search queries that lead to a page being immediately abandoned are strong signals about where the manual is failing:

• A frequent search with no matching result is a direct signal of a missing page or missing terminology — the reader is using a term the manual does not.
• A page with high traffic but a high bounce rate suggests the page is being found but not answering the question that brought the reader there.
• A troubleshooting page with sustained high traffic long after the underlying issue should have been fixed is a signal to raise with product or engineering, not just to keep the page updated — see TS-25: Technical documentation's section on support-driven documentation.

Close the loop

Feedback and usage data are only useful if they change what gets written or prioritized next. Reviewing this data SHOULD be a routine part of maintaining the manual, not a one-off audit — see Versioning and maintenance for tying that review into a regular cadence.

References

• Ubl, M (2020). Design Docs at Google. Industrial Empathy. — Not about user manuals directly, but the underlying point — that a document’s structure should match how its reader actually consumes it — applies equally to task-based user documentation.
• Write the Docs. — Community-maintained guide covering both developer and end-user documentation practices, including several of the structural patterns referenced in this standard.
• Nielsen Norman Group (2021). User Manuals: The Beauty of Task Orientation. Nielsen Norman Group. — The primary source for the task-oriented structure recommended in Task-based writing.