Documentation should be searchable and task-oriented

What it is

When documentation is needed, readers should be able to find an answer using their task goal, an error string, an object name, or a role. Task-oriented documentation is organized around "how to approve an invoice," "why can't I publish," or "how to transfer ownership," not stacked by internal module, version chapter, or feature manual. It builds on the previous card, "ideally no documentation needed": once documentation does get used, this one governs whether it can be found at the moment it is needed.

Why it happens

A user searches with a goal or a symptom in mind, with no idea how the product's internal modules are divided or which internal subsystem a feature belongs to. If the documentation's information architecture is built around code modules or the feature menu hierarchy, the answer can exist somewhere and still not be found, because the documentation and the user are not speaking the same language — the search fails not from missing content but from a mismatch between how it is organized and how the user phrases the question. Searchability is therefore not just "is there a search box"; it includes a search index, synonym mapping, an error-code-to-article lookup, role-based filtering, and whether the current interface context can carry parameters straight into the search — clicking an error message should prefill the search term instead of requiring the user to retype a description of the symptom. The answer itself must also cover preconditions, steps, required permission, expected result, and failure handling in full; missing any one of these leaves the user having read the article and still unable to finish, forced to search again with a new question.

Where it stops holding

Task orientation does not mean rejecting reference manuals. API field descriptions, a complete list of configuration options, and regulatory text genuinely need a manual that can be looked up entry by entry; a task-oriented article can link to it, but should not try to shred the manual into a pile of task articles — doing so loses the completeness a reference needs. Across multiple versions, tenants, or regions, the same task title can map to different steps, so an article must state which version, plan, or region it applies to, or a user following steps that do not match their own account ends up more confused than if they had found nothing. Another way this goes wrong is over-fragmentation: splitting one complete workflow into a dozen one- or two-sentence articles is technically "task-oriented," but readers lose the sequence and dependency between steps and have to piece the full picture back together across articles themselves.

Applying it

• Build the article title and alias vocabulary from raw support-ticket wording, on-site search logs, and the label text that appears in the interface, rather than reusing internal product feature names.
• Give every article a fixed structure: applicable role, applicable version, required permission, steps, expected result, failure recovery, and a link back to the relevant part of the interface.
• Support reverse lookup from error text: the error copy a user sees in the interface should link directly to the corresponding solution article, without requiring the user to redescribe the problem to search for it.
• How to check: test three-click reachability using real search terms rather than titles the documentation author chose, log queries that return no results, and turn them directly into content gaps or synonyms to add.

Related

• Same group: B3.10.1 The interface should ideally work without documentation · B3.10.3 Help entry points should sit near where the problem occurs
• Nearby: T1 Interface Copy and Content · Q3 Help and Documentation
• Search terms: task-oriented documentation · help search · knowledge base · information architecture