How to Write Documentation People Actually Use

Why Documentation Gets Ignored

Most documentation is written to document — to prove that something was explained, to cover liability for "it's in the docs," or to satisfy a process requirement. This documentation exists; people know it exists; they don't use it.

The documentation people use is written to help — to answer a specific question, to walk through a specific process, or to explain a concept in a way that lets someone do something they couldn't do before. The distinction between these two types of documentation is not what they say — it's who they're written for.

Author-centric documentation covers what the author knows, organized in a way the author finds logical, at the level of detail the author considers appropriate. Reader-centric documentation answers the question the reader is asking, organized for how the reader will navigate, at the level of detail the reader needs to act.

The observable difference: author-centric documentation makes readers work — they scan, skim, and search before finding the answer, if they find it at all. Reader-centric documentation makes the work obvious immediately — the answer to the question is visible in the first scroll.

Most documentation is author-centric by default because writing is easier when you start from what you know. Writing reader-centric documentation requires first understanding what the reader is trying to do, which is a separate and harder problem.

---

The Reader's Information Need

Every piece of documentation a reader consults is in service of an information need. The information need is specific and usually time-constrained: the reader needs to know something right now, because they're in the middle of doing something.

The three most common information needs in organizational documentation:

1. Task completion: "I need to submit an expense report." The reader knows what they're trying to do; they need the steps. The information need is satisfied when the reader has completed the task.

2. Reference lookup: "I need to know the deadline for performance reviews" or "I need the API endpoint for user authentication." The reader knows exactly what they're looking for; they need one specific fact. The information need is satisfied when they find the fact.

3. Decision support: "I need to understand the options for this process so I can choose the right one." The reader is in the middle of a decision; they need enough context to choose. The information need is satisfied when they understand the options and their trade-offs.

A piece of documentation that's trying to serve all three needs simultaneously serves none of them well. The task completion reader doesn't want background context before the steps. The reference lookup reader doesn't want a tutorial. The decision support reader doesn't want just the steps without the why.

Before writing any piece of documentation, identify the primary information need: task completion, reference lookup, or decision support. Write for that need. If the same topic requires all three, write three separate documents and link them.

---

The Diátaxis Framework Applied

Daniele Procida's Diátaxis framework (2017-present, diátaxis.fr) provides a systematic way to think about documentation types and their structure. It identifies four modes:

Tutorials: Learning-oriented. The reader is learning for the first time. The tutorial guides them through a sequence. They don't yet know what they don't know. "Set up your development environment for the first time."

How-to guides: Task-oriented. The reader knows what they want to do; they need the steps to do it. They have some competence already. "How to reset your password."

Reference: Information-oriented. The reader needs a specific fact. They want to find it quickly and leave. "Keyboard shortcuts." "API endpoints." "Policy deadlines."

Explanation: Understanding-oriented. The reader wants to understand something conceptually. They're not trying to do a task right now; they're trying to build a mental model. "How our authentication system works."

The reason this framework produces better documentation: most documentation conflates these modes. A "tutorial" that assumes prior knowledge is actually a how-to guide. A "reference guide" that includes explanatory prose makes facts harder to find. Separating documentation by mode makes it easier to write (because you know what you're writing and for whom) and easier to use (because the reader can find the mode that serves their need).

Practical application: Before writing, ask: "Is the reader learning something new (tutorial), doing something specific (how-to), looking up a fact (reference), or trying to understand something (explanation)?" The answer determines the structure.

---

Writing Task Documentation That Works

How-to guides and tutorials are the most commonly written documentation types and the most commonly wrong. The structure that produces documentation people complete:

The title is the task. "Submitting an Expense Report" is a good title. "Expense Policy Information" is a bad title. The title should be a verb phrase that matches what the reader typed into the search box.

The summary is the answer. The first sentence answers the primary question: "To submit an expense report, navigate to the Expenses app and upload your receipts within 30 days of the expense. Processing takes 5-7 business days." A reader who only reads this sentence has the essential information. Longer documentation adds detail for readers who need it, but never buries the primary answer.

Steps are numbered and short. "Click Submit" is a step. "In the Expenses application, after reviewing your receipts and categories, ensure that all fields are complete and that you have attached the appropriate supporting documentation for each line item, and then click the Submit button located in the lower right corner of the form" is not a step — it's a paragraph with a step at the end. Each step is one action. Each action is verifiable: the reader does it and can confirm it worked.

Prerequisites are stated first. If the reader needs to have completed something before following the steps, say so before the steps. "Before starting, ensure you have access to the Expenses app (request access via the IT Help Desk if needed)." A reader who gets to step 3 and discovers they don't have the required access has wasted time.

Edge cases are called out explicitly. The most common source of calls to the help desk: the reader followed the instructions and something different happened. Edge cases that produce different outcomes belong in the documentation: "If you're submitting for a client entertainment expense over $500, you'll also need manager approval before submitting."

---

Writing Reference Documentation That Works

Reference documentation has one job: the reader finds the fact they need in under 30 seconds.

Structure by the way readers search. A reference page for keyboard shortcuts should be organized alphabetically or by function — not by the order in which the shortcuts were added to the product. A reference page for API endpoints should be organized by endpoint function, with a consistent format for each entry.

Density is a virtue. Reference documentation that includes explanatory prose around every fact is harder to scan than pure reference documentation. If the explanation is needed, link to it — don't embed it in the reference page. The reference page is for facts; the explanation page is for context.

Consistent formatting. Every entry in a reference document should have the same format. "Keyboard shortcut | Description | Availability" for every row. "Endpoint | Method | Parameters | Response" for every API. Consistent format makes scanning faster because the reader knows where to look.

Keep it current. Reference documentation that's out of date is actively harmful — a reader who uses the wrong API endpoint, or the wrong deadline, acts on bad information. Reference documentation needs the most rigorous maintenance, because it's used for time-sensitive decisions.

---

The Scannability Principle

Employees who consult documentation in the middle of a task are not reading — they're scanning. They scan until they find something that looks relevant, then they read that part. Documentation written as flowing prose forces sequential reading. Documentation written for scanning lets the reader find the relevant section immediately.

Headers as navigation: Use descriptive headers that answer the question the section addresses, not headers that name what the section is about. "Who approves expense reports?" is a better header than "Approval Process." "How long does reimbursement take?" is better than "Reimbursement Timeline."

Bold key information: The specific fact the reader is looking for — a deadline, an amount, a contact — should be bold or otherwise visually distinct so it's findable during a scan without reading.

Short paragraphs: A five-sentence paragraph requires reading. A two-sentence paragraph or a bulleted list can be scanned. For documentation consulted under time pressure, shorter is almost always better.

Anchor links for long pages: Long reference pages should have a table of contents with anchor links at the top. A reader who needs the "expense categories" section of a 20-section expense policy page should not scroll through 15 sections to find it.

---

Common Documentation Anti-Patterns

The passive voice wall: "It is required that all expenses be submitted within 30 days of the date incurred, and appropriate documentation must be attached in order for reimbursement to be processed." Compare: "Submit expenses within 30 days. Attach receipts for all expenses." Active voice, specific instructions, half the word count.

The hedge parade: "You may want to consider checking with your manager before submitting expenses that could potentially be in a gray area regarding policy eligibility." Compare: "Check with your manager before submitting non-standard expenses." Remove hedges from instructions; add explicit uncertainty where it genuinely exists.

The policy dump: Copying policy language into knowledge base documentation. Policies are written for legal precision; documentation is written for task completion. They have different audiences and should be different documents. Reference the policy; don't reproduce it.

The "see also" maze: Linking out to 12 related pages without explaining which link is most relevant. "See also" sections are useful when they link to one or two related pages with descriptions. A "see also" with 10 links is not navigation — it's abdication.

The out-of-date screenshot: Screenshots become outdated faster than text. A screenshot of a UI that no longer exists sends the reader looking for something they can't find. For rapidly changing UIs, prefer text instructions over screenshots. When screenshots are needed, note the date and application version they depict.

---

The Edit That Makes Documentation Useful

Most documentation improves most with one edit: the "reader's first question" edit.

After writing, read the document as if you're the reader. Ask: "What question am I trying to answer right now?" Then check: is that question answered in the first two sentences? If not, move the answer there.

The second edit: "What would stop me from completing this task?" For task documentation, identify every place where a reader might be confused or might need something that's not mentioned. Add it.

The third edit: "What would I search for to find this page?" Is that search term in the title? If not, add it.

These three edits take 10 minutes and produce documentation that reliably answers the question rather than documentation that contains the answer somewhere in its pages.

---

Worked Example: Rewriting a Benefits FAQ

Before (author-centric):

Our benefits package includes health, dental, and vision insurance, as well as a 401(k) plan with company matching, generous PTO, and other perks. Employee benefits are a significant part of the total compensation package and we believe in providing comprehensive coverage to our team.

Health benefits are available from the first day of employment. The company covers 80% of employee premiums and 60% of dependent premiums. We offer three health plans: the Standard plan, the Premium plan, and the HSA-compatible plan. Enrollment takes place during the annual open enrollment period in November or within 30 days of a qualifying life event.

What's wrong: The reader who needs to know "when can I enroll in health insurance?" has to read the entire section before finding "November" and "30 days." The first paragraph contains no actionable information.

After (reader-centric):

When can I enroll in health insurance?

• Within 30 days of your start date (new hire enrollment)
• During November open enrollment (annual, for the following year)
• Within 30 days of a qualifying life event (marriage, birth, loss of other coverage)

What plans are available? Standard, Premium, or HSA-Compatible. [Compare plans →]

What does the company pay? 80% of employee premiums, 60% of dependent premiums.

The same information, organized by the questions readers actually ask, with the answers immediately visible during a scan.

---

Key Takeaways

1. Identify the reader's information need before writing: task completion, reference lookup, and decision support require different structures; documentation that conflates them serves none well.
2. The title is the task and the first sentence is the answer: a reader who finds the title should know they've found the right document; a reader who reads the first sentence should have the essential information.
3. Write for scanners, not readers: headers that answer questions, bold key facts, short paragraphs, and anchor links convert flowing prose into a navigation tool.
4. The Diátaxis framework (tutorial, how-to, reference, explanation) resolves the most common structural confusion: know which mode you're writing before you write.
5. The reader's first question edit is the highest-leverage revision: after drafting, check that the question the reader has when they arrive is answered in the first two sentences — if not, move it there.

---

Conclusion

Documentation people use is not documentation written carefully — it's documentation written from the reader's perspective. The reader has a specific question, is under time pressure, and will scan before reading. Documentation that makes the answer visible during a scan, that structures tasks as numbered steps with stated prerequisites, and that separates modes (how-to, reference, explanation) so each serves its audience cleanly is documentation that gets used. The practice — identify the reader's need, write the answer first, edit for scannability — is not complex. The result, over months of consistent application, is a knowledge base where people find what they need and trust what they find.

Try WebSnips free — save and annotate documentation best practices, writing guides, and reference materials with your own notes on what works, tag by content type and team, and build the organized knowledge library that makes every document you write more useful.