Background

User documentation requirements

David Watson

Date published: .

In this article, we'll look at how to define requirements for user documentation — not as a bureaucratic exercise, but as a practical way to stop writing in the dark.

What is a documentation requirement — and why you're flying blind without one

Say you're writing docs for a product, and someone asks what your requirements are. Most teams answer with something like "the docs should be clear." That's not a requirement — it's just a wish. A requirement is something you can put a number on and then go check. Take this: a first-time user finds the description of the "Save" button within 20 seconds. Either they do or they don't. You can run that test. You can't run the other one.

A simple template for writing measurable requirements:

When [user persona] performs [action], the [documentation element] must allow them to achieve [outcome] within [time or number of steps].

Example: "When a first-time user performs a password reset, the help topic must allow them to complete the process within 45 seconds without assistance."

Why this works: This works, because every part is testable. You can recruit a first-time user, time them, and count whether they needed help.

If you have clear, measurable requirements, then you can answer the three essential questions: Is this work done? Is it good enough? And when does it need to be redone? Instead, you rely on gut feelings — "I think it's clear," "Users don't complain," or "This is how we've always done it." In practice, this leads to endless rewrites, conflict with developers, and documentation that takes months to build but solves none of the user's problems.

The acid test of a good requirement. Can you walk into a room, hand it to a colleague who knows nothing about the project, and have them tell you after two minutes whether it's been met or not? If not, it's not a requirement — it's an opinion.

Before and after: turning a vague requirement into a measurable one

Before (vague, untestable): "The documentation must be easy to navigate."

After (measurable, testable): "A first-time user must be able to find the 'Export report' topic in two clicks from any help page."

Why the second one works: You can test it with real users. You can count the clicks. You can set a pass/fail threshold. You can't argue with the result.

Requirements vs. standards: the map vs. the highway code

People get this wrong all the time — even seasoned technical writers. They say things like "Our requirements follow ISO 82079" or "We need to comply with the company style guide." But ISO standards and style guides are not requirements, just standards and they prescribe how to do something, not what to achieve.

AspectRequirementStandard
What it definesThe goal, the outcome, the measurable resultThe form, the formatting rules, the process
Example"User finds the answer to a common question within 30 seconds.""All H2 headings must be 16pt Arial, bold."
How to testTest it — time it, A/B test it, watch a user try itInspect it — does it match the template? Yes/No
FlexibilityRigid. If you don't meet it, you fail.Internal standards can be recommendations; external ones (like ISO) may be mandatory.
Who defines itBusiness, users, support, analytics, regulatorsGovernments, industry bodies, internal style committees

Try to think of requirements as a destination on a map. For example you're not saying "let's head vaguely east." You're saying you need to be in City X in under three hours instead. Standards are the rules of the road and the format of your license plates. You can get to City X in 3 hours even if your license plates don't meet the local standard. But you cannot get there if you have no destination. And if you follow every rule to the letter but have no idea where you're going, you end up nowhere.

The real-world pain. Teams write a 50-page formatting guide — font choices, padding, screenshot borders, tag structure — but never define a single measurable requirement about content. The result is beautiful, useless documentation. Conversely, some teams produce a flood of vague requirements ("documentation must be complete," "must cover all scenarios") but have no standard to ensure consistency. One writer says "Click the OK button," another says "Press OK," a third says "Select OK." The user is confused, even though the requirements are technically met.

What actually works? A tight coupling between measurable requirements and minimal but effective standards that help you meet them. Example: Requirement: "A user can complete the import workflow without contacting support." Standard: "Every step in a workflow must be a numbered list, start with an action verb, and describe exactly one action."

Types of requirements: from content to accessibility

Documentation requirements fall into several groups, where each addresses a different aspect of quality, don't ignore any of them.

1. Content requirements

  • Completeness. Does the documentation cover all features and scenarios the product claims to support? Here's a hidden nuance: 100% completeness is both impossible and undesirable — it leads to documentation that nobody reads. Document not the entire knowledge base, only the 20% of features used by 80% of your users, and put the rest in a reference section.
  • Currency. Does the documentation match the version of the product that's actually shipping? Here's a quick way to find out: pick a section at random. Walk through it in the UI. The moment something doesn't line up, the requirement is broken. In practice, currency decays fast — after three months, most documentation is already misleading.
  • Accuracy. Check whether the descriptions, examples, and screenshots technically correct. It's not that easy to test accuracy because it requires reproducing every step. That's why many companies skip this step and then regret it.

2. Structure and navigation

  • Hierarchy. Is there a logical table of contents? Are sections grouped meaningfully? Is numbering consistent if used?
  • Search. Is it possible to find information by keywords, synonyms, and even with typos? That's measurable. The first relevant result should show up within 5 seconds. And the top three results should be relevant at least 80% of the time. This is one of the failures that comes up most often.
  • Link integrity. Do all internal links work, and do they go where users expect? Sounds like a basic thing to check. In practice, though, up to 15% of the links in a large PDF manual turn out to be broken.

3. Language and style

  • Readability. Can your target audience actually understand what you've written? For English, there's the Flesch-Kincaid score — it gives you a number. In technical documentation, you're aiming for short sentences, under fifteen words or so, and as little passive voice as you can manage.
  • Consistency. Does every button and field have the same name throughout the documentation? This requires a glossary and often automated linters — without a standard, it's almost impossible to enforce.
  • Visuals. Are complex actions supported by screenshots or diagrams? Measurable: at least 70% of sections in a "Configuration" chapter should include a visual.

4. Non-functional requirements

  • Accessibility (A11y). Can people with disabilities actually use the documentation? That means screen reader support, enough color contrast, keyboard navigation — the things that decide whether someone can get through it at all. By 2026, this is not optional. In many jurisdictions, it is a legal requirement under WCAG 2.1 Level AA.
  • Maintainability. Once the product changes, how long does it take to update a section? There's a number for this: two hours, no more, for a section of average size. Go past that and your maintainability requirements are broken. Time to refactor, or time to switch tools.
  • Publication format. Are you putting the documentation out in the formats your users actually need — web help, PDF, CHM, embedded help? The requirement is simple enough: at least two formats, and one of them has to be web-based.

5. Localization and translation

Localization requirements are not optional if your product serves multiple languages or regions. Even manuals for English-only products should be ready for non-native speakers.

  • Terminology is where things fall apart first. Keep a glossary mapping source terms to approved translations — without one, the same button ends up with five different names across localized versions.
  • Then there's readability. Non-native speakers need simpler vocabulary and shorter sentences than native English readers, and a Flesch-Kincaid score of 60 or higher is a reasonable target.
  • Cultural adaptation is trickier. Examples, metaphors, idioms — they rarely survive translation, so steer clear of anything tied to one region or culture.
  • And version synchronization. The translated version has to be updated when the source is, not later. Translation lag must not exceed 5 working days after the source is updated.

When these requirements apply: Any product with an international customer base. When they don't: A product with a purely domestic audience — but even then, non-native speakers may still use it.

6. Mobile-first and responsive design

Most people reach documentation from a phone or a tablet now. If it doesn't read well on mobile, it doesn't read at all.

  • That starts with responsive layout. Content has to reflow to whatever screen it lands on, with no horizontal scrolling anywhere. Test it on a viewport as narrow as 320px.
  • Then there's tapping. Buttons, links, accordions — anything interactive needs to be at least 44px tall, or people will miss it with their thumb.
  • And font size. Body text on mobile should be 16px minimum. Go smaller and you're straining eyes, which shows up in your bounce rates.
  • Table and image scaling: Tables must be horizontally scrollable or simplified for mobile. Images must resize proportionally.

Measurable requirement: "The full documentation set must be navigable and readable on a 320px-wide screen with no more than two pinch-to-zoom actions required per page."

How to gather requirements: three sources that actually work

Requirements don't come from the technical writer's head. They come from the real pain points of users and the business. Here are three ways to gather requirements that will survive contact with reality.

1. Support logs and search queries

Export the last 500 support tickets. Group them by topic. Anything that appears more than three times is a potential documentation requirement. Example: 40 tickets about "how to reset password" → requirement: "The 'Reset password' topic must be reachable in one click from the help homepage." Same for search queries inside your help system: if users type "import from excel" a hundred times a week and no matching topic exists — that's a requirement to create one.

2. Usability testing of documentation

Reading your own docs won't tell you whether they work. You need someone else at the keyboard. Pick three things a new user should manage on their own — register, create a report, configure notifications, whatever your product actually asks of them. Then sit there and watch what happens. Two minutes is the line. One wrong turn is the line. Cross either one and the documentation didn't do its job. This is the single best way to generate measurable requirements.

3. Analytics on documentation usage

In your web-based help, look at which sections people open, how long they read, and where they leave. If a section called "Integration setup" averages 5 seconds of reading time — either it's unnecessary or it's unreadable. That leads to a requirement like "Average reading time for a 1000-character section should be at least 30 seconds." Crude, sure. But the point holds: if nobody's using it, it shouldn't be there./p>

So what do you do when none of this applies? Say you've got a brand-new product — no users yet, no support history to draw on. Then you work from what's out there: competitor docs, and whatever your own team already knows. But expect to rewrite everything in six months.

How to prioritize requirements: not everything is equally important

You can't do all of it at once. That's where MoSCoW comes in — a simple way to sort documentation requirements when time and resources are tight.

CategoryMeaningExample
Must haveWithout this, the documentation fails its core purpose"Users can find the 'Reset password' topic from the help homepage."
Should haveImportant but can be delayed if necessary"All screenshots include numbered callouts."
Could haveDesirable but not urgent — nice to have"Documentation includes embedded video tutorials."
Won't haveExplicitly excluded for this release"Full translation into three languages."

When this works: When you have a fixed release deadline and need to make trade-offs quickly. When it doesn't: If your organization treats every requirement as "must have" — you'll need to push back with data from support logs or usability tests.

hidden costs and practical complexities

Even perfect requirements hit a wall when they meet reality. Here's what usually breaks them.

1. Requirements go stale faster than the product

You gathered requirements, wrote the docs, tested them — everything is green. Two months later, a new version ships with a new screen and renamed buttons. The "all features documented" requirement is already broken. The fix needs to happen immediately, but nobody budgets time for it. Six months later, those requirements are fiction.

What to do: Build a "maximum age" clause into your requirements. For example: "Documentation is considered current if less than 5% of content by volume conflicts with the product." And automate detection — screenshot diffing tools or regular audits every two weeks.

2. Conflicting requirements

"Documentation must be complete and cover every feature." Also: "Users must find what they need in 30 seconds." Completeness and speed pull against each other. The fuller the document gets, the harder it becomes to search. So you split it: a complete reference manual, plus a set of quick-start guides for the key scenarios. But you need to write this trade-off explicitly into your requirements — otherwise you'll ping-pong between "add more content" and "cut the fat" forever.

3. Requirements written for compliance, not for users

Management demands "ISO 82079 compliance" or "follow the style guide." Nobody tests whether any of that actually helps users. Weeks go into formalities, and user satisfaction doesn't move.

What to do: For every compliance-driven requirement, add a measurable user-focused counter-requirement. Example: "All sections required by ISO 82079 must be written so that an average user can find the relevant information within 1 minute." Now the formal exercise becomes a tool.

Search and analytics — the underrated requirements

Search is the main interface to documentation in 2026, especially as help systems increasingly handle support queries. A bare-minimum set of search requirements:

  • Full-text search across all documentation with relevance ranking.
  • Synonym support ("reset password" should match "recover password").
  • Auto-correction of typos (edit distance ≤ 2).
  • Average search response time under 1 second.
  • First-result accuracy at least 70% on a test set of common queries.

Measuring user satisfaction: CSAT, CES, and NPS for documentation

Requirements are only useful if you can measure whether you've met them. Here are three proven methods:

  • CSAT (Customer Satisfaction Score): After reading a help section, ask: "How helpful was this information?" Scale of 1-5. Target: at least 80% of responses are 4 or 5.
  • CES (Customer Effort Score): Ask: "How easy was it to find the information you needed?" Scale of 1 (very difficult) to 7 (very easy). Target: average score of 6 or higher.
  • Task completion rate: Observe users attempting a task. If they complete it using only documentation, that's a pass. Target: at least 80% completion rate on top-10 user tasks.

When these metrics work: When you have enough daily traffic to get statistically significant data (at least 50 responses per section). When they don't: Low-traffic documentation — use usability testing instead.

How this affects tool choice: If your help authoring tool can't meet these search requirements, you either need a new tool or you need to revise your requirements. A beautifully styled manual is useless if nobody can find "how to delete my account."

Documentation requirements for AI agents

Large Language Models (LLMs) increasingly parse documentation to answer user questions. If your documentation isn't structured for machine readability, it won't appear in AI-generated responses.

  • Semantic markup: Use Schema.org and proper HTML5 semantic tags (article, section, aside, nav). This helps LLMs understand the hierarchy and purpose of each block.
  • Clean HTML: Avoid deeply nested tables, inline styles, and complex JavaScript-dependent content. LLMs parse HTML directly — messy code reduces accuracy.
  • Unique identifiers for each step: Each task step should have a logical, predictable ID (e.g., section id="reset-password-step-1"). This allows AI agents to reference specific steps.
  • Explicit relationships: Use link text that describes the destination ("See the password reset guide") rather than "Click here." LLMs use link text to build context.
  • Metadata in head: Include clear title, description, and keywords in the head of each page. AI agents often read these first.

Measurable requirement: "The documentation must pass an LLM extraction test — an AI agent must be able to produce a correct, step-by-step answer to at least 8 out of 10 common user questions using only the documentation's HTML content". Explore a series of our articles on developing AI-powered user documentation.

Documentation KPI dashboard: what to track

A simple dashboard can answer: "Is our documentation getting better or worse?" Here are the key metrics:

  • Search success rate: Percentage of searches that lead to a click within 3 seconds. Target: ≥ 70%.
  • Task completion time: Average time users spend on a topic before leaving. If it's too short, they didn't find what they needed. If it's too long, the content is confusing.
  • CSAT trend: Monthly average of satisfaction scores. A downward trend is a leading indicator of problems.
  • Support deflection: Percentage of users who visit the help system and don't file a support ticket. Target: ≥ 60%.
  • Section-level bounce rate: Pages where users leave immediately. Below 40% is healthy.

How to present this: A weekly email with the numbers and a "green/yellow/red" status for each metric. The dashboards in Google Analytics and your help tool are your friends.

Requirements and standards together: how not to create bureaucracy

A 30-page "Documentation Requirements" document that mixes formatting rules (font size, screenshot numbering) with real content requirements (search time, scenario coverage) is a recipe for unreadable, unenforceable policy. Here's a better approach:

  • Separate them clearly. One document for measurable requirements (for managers and leads). Another for standards (for writers).
  • Make requirements testable. Instead of "documentation must be complete," write "documentation must cover at least 90% of scenarios in list S001–S050." Instead of "documentation is easy to find," write "user finds a section by a keyword from its title in 2 clicks."
  • Automate your standards. If a standard says headings must look a certain way, or a term must be used a certain way, write a linter or a script that checks it for you. The standard stays visible, and it stops getting in the way of actual work.

Conclusion

1. A requirement is a measurable condition. Anything else is noise.

2. Standards define form and process. Without a goal, they are meaningless.

3. Gather requirements from support logs, usability testing, and analytics — not from thin air.

4. Requirements and standards shouldn't live in the same document. They're aimed at different people, and mixing them makes both harder to use. Requirements are for whoever decides what gets built. Standards are for whoever has to write it.

5. The biggest killers of requirements in practice: obsolescence (new product versions), conflicts (completeness vs. speed), and compliance without purpose.

6. Include search and analytics in your requirements — in 2026, they matter more than layout.

7. If you can't test a requirement within 10 minutes on a real example, rewrite it or delete it. Untested requirements are dead requirements.

8. One good requirement (e.g., "user finds the 'Export' button description within 20 seconds") is worth a dozen vague statements.

9. Requirements have a shelf life — no longer than your release cycle. Budget for updates, or they will expire.

10. Don't try to fix everything in one sprint, pick three requirements that hit your biggest support pain points.

11. Can a colleague who knows nothing about your project tell you whether it's been met after 2 minutes? If not, it's not a requirement.


See also