TapCub is live — analytics, insights and live chat, free on one platform
Product News

How to Write a User Guide: Structure, Annotated Outline and Testing

How to write a user guide that reduces support tickets: start from 90 days of tickets, use an annotated outline, write steps by Microsoft's rules, test with five people and measure the result per 1,000 users.

Lin Zhou Published Nov 20, 2026 12 min read Product News
Sample data: covered categories fell 44.0% and uncovered ones fell 12.5% over the same period, so the guide accounts for about 31 percentage points of the change.Sample data

To write a user guide, start from the questions customers already ask: sort the last 90 days of support tickets into task categories, write one section per category in a fixed skeleton (title, before you start, numbered steps, result, if it did not work), test it with five people who have not seen the product, and measure tickets per 1,000 active users against categories you did not document. In the sample, four sections covered 70% of tickets.

What you will learn

  • Write for the top ticket categories first: in the sample, four task sections covered 70% of 400 tickets
  • Write steps with one action each, a named control and a visible result, because users read only about 20% of a page
  • Credit the guide only with the excess over uncovered categories: -44.0% versus -12.5% in the sample, about 31 points

What is a user guide, and how is it different from a manual or a tutorial?

A user guide is task-based documentation that tells a customer how to get something done with your product, step by step. Its test is simple: a person with a goal opens it, follows it and succeeds without asking anyone. The words "user guide", "user manual" and "help article" overlap, but the shape of the content differs.

TypeAnswersReaderTypical shape
User guide"How do I do X?"Someone mid-taskNumbered steps for one task, with the result stated
Tutorial"Teach me the basics"A new userA guided path through one realistic project
Reference"What does this setting do?"An experienced userComplete lists of fields, options and limits
Troubleshooting"Why is it not working?"Someone stuckSymptom, cause, fix

Most "user guides" fail because they try to be all four at once. This page treats the guide as the task document and keeps the others separate and linked. The measure of success is not page count but support tickets avoided: each section should map to a question your customers actually ask. Training your team to point customers to the right section is covered in customer service training.

How do you decide what the user guide should contain?

Start from the questions people already ask, not from a feature list.

  1. Collect the last 90 days of support contacts: tickets, chats, emails.
  2. Give each a category. Use ten categories or fewer, named as tasks ("reset a password", not "account issues").
  3. Count and sort. Work out each category's share and the running total.
  4. Write for the top categories first. They are where the saved tickets are.
  5. Keep an "other" bucket. If it grows past about 15%, your categories are too coarse.

Sample data: 400 tickets in 90 days.

CategoryTicketsShareRunning total
Reset password9624.0%24.0%
Invite teammates7218.0%42.0%
Connect a data source6416.0%58.0%
Export a report4812.0%70.0%
Billing and invoices4411.0%81.0%
Notification settings307.5%88.5%
Other4611.5%100.0%

The first four categories account for 70% of the tickets (96 + 72 + 64 + 48 = 280, and 280 ÷ 400 = 70%). That is the guide's first release: four task sections, not forty. Ignore the temptation to document features nobody asks about.

What does a good user guide outline look like?

Use the same skeleton for every task so readers learn where things are. Each part has a job, and a ticket type it targets.

SectionWhat goes in itRuleTargets
TitleThe task as the user would say it: "Invite a teammate"Verb first, no product jargonSearch and navigation
Before you startPermissions, prerequisites, time neededList only what blocks the task"I can't see the button" tickets
StepsNumbered, one action each, ending at the visible result3 to 9 steps; split longer tasks"How do I…" tickets
ResultWhat the user should see when it workedOne sentence, with the screen name"Did it work?" tickets
If it didn't workTwo or three common symptoms with fixesSymptom, cause, fixRepeat contacts
Related tasksLinks to the next likely taskTwo or three at mostFollow-up tickets

Put a short quick start before the task sections: five steps or fewer to the first success, so a new user is not asked to read everything. Add a glossary only if you cannot avoid a term; otherwise rewrite the term out.

SectionWhat goes in itTicket type it targets
TitleThe task in the user's words, verb firstSearch and navigation
Before you startPermissions and prerequisites that block the task"I can't see the button"
Steps3 to 9 numbered steps, one action each"How do I..."
ResultWhat the user should see when it worked"Did it work?"
If it didn't work2 or 3 symptoms with cause and fixRepeat contacts
Related tasksTwo or three links to the next likely taskFollow-up tickets

Use the same skeleton for every task so readers learn where things are.

How should you write the steps?

Readers do not read; they scan. Nielsen Norman Group's study of 45,237 page views from 25 users, collected in 2005, found that users have time to read at most 28% of the words on an average web page during a visit, and that 20% is more likely (Nielsen Norman Group). Write so that the 20% they read is the right 20%: the step verbs and the buttons.

Microsoft's style guide gives concrete rules for step-by-step instructions (Microsoft Style Guide):

  • Use a numbered list for multi-step procedures, and a separate step for each instruction; short steps in the same place on screen can be combined.
  • If there could be confusion, say where the action takes place before describing it.
  • Start each step with an imperative verb, and use a complete sentence.
  • Include the action that completes the procedure, such as selecting Apply.
  • Do not overwhelm: try to fit all the steps on one screen.
  • Make headings parallel, and do not let an introductory sentence repeat the heading.

Rewrite example. Before: "The user should navigate to the settings area and then they will find the option to add team members which can be clicked." After:

  1. In the left menu, select Settings.
  2. Select Team, then Invite member.
  3. Enter the person's email address and choose a role.
  4. Select Send invite. The person appears in the list as Pending.

The "after" version has four verbs, four named controls and a visible result. Check every step against this: is there one action, a named control and, at the end, an observable outcome?

How do you write the "if it didn't work" part?

Keep it as a table of symptoms, because people search by what they see.

SymptomLikely causeFix
"Invite member" is greyed outYour role cannot inviteAsk an admin to change your role or send the invite
Invite sent but nothing arrivesWrong address, or spam filterCheck the address; ask the person to check spam; resend
Person appears twiceTwo invitations to different addressesRemove the unused one under Team

Two rules: every symptom is a thing the reader can observe, and every fix is an action, not advice ("be careful with email addresses"). If a symptom keeps producing tickets after the guide ships, the fix text is wrong or the symptom is not specific enough.

How do you test a user guide before publishing it?

Give the guide to someone who has not seen the product and watch. Nielsen's model of usability testing says the share of problems found with n testers is 1 − (1 − L)ⁿ, where L is the share a single tester finds; with L = 31% five testers find about 84% (the article rounds to 85%) (Nielsen Norman Group, 2000). Five people, run one at a time, is a sensible size for a guide.

Protocol, for each task:

  1. Give the person the goal ("add a teammate"), not the steps.
  2. Let them use only the guide. Do not help; take notes at each hesitation.
  3. Record completed without help (yes or no), time to finish and the step where they paused or erred.
  4. Fix the guide at each pause, not the person.
  5. Re-test the changed steps with new testers.

A working bar: at least 4 of 5 complete without help. If 2 of 5 stall at step 3, step 3 is the bug.

How do you measure whether the guide cut support tickets?

Raw ticket counts mislead, because your user base changes. Normalise per 1,000 active users and compare against categories you did not touch.

Sample data: before the guide, 400 tickets and 20,000 active users, which is 400 ÷ 20,000 × 1,000 = 20.0 per 1,000. After, 310 tickets and 22,000 active users: 310 ÷ 22,000 × 1,000 = 14.1 per 1,000, a 29.5% fall. (The raw count fell only 22.5%, because the user base grew.) By category:

CategoryGuide writtenBefore, per 1,000After, per 1,000Change
Reset passwordYes4.801.82−62.1%
Invite teammatesYes3.602.50−30.6%
Export a reportYes2.401.73−28.0%
Covered: three categories10.806.05−44.0%
Connect a data sourceNo3.202.82−11.9%
Billing and invoicesNo2.201.91−13.2%
Notification settingsNo1.501.27−15.2%
OtherNo2.302.05−11.1%
Not covered: four categories9.208.05−12.5%

The not-covered categories fell 12.5% with no guide. That is your control: other things changed (product fixes, a seasonal dip, a better onboarding email). The guide's effect is the excess: −44.0% versus −12.5%, about 31 percentage points. Credit the guide with that, not with the full 44%.

Pair the ticket count with two supporting numbers: the guide pages' views and how many of those visits end without a contact. A guide that is read and still produces tickets has unclear steps; a guide nobody opens has a findability problem.

app.tapcub.com

Tickets per 1,000 active users, before and after

sample data
Covered by the guide, before10.80
Covered by the guide, after6.05
Not covered, before9.20
Not covered, after8.05
Sample data
Sample data: covered categories fell 44.0% and uncovered ones fell 12.5% over the same period, so the guide accounts for about 31 percentage points of the change.

How to connect the guide to customer questions with TapCub

TapCub does not write or host your guide. It helps you find what to write and see whether it works, if you use TapCub live chat on the same site and the same visitor ID. The same ticket-first approach works with chat conversations:

  1. Find the questions. Chats that reach a person are labelled with the reason: no knowledge match, the model could not answer, the visitor asked, the turn limit or an agent took over. In the knowledge base's Draft inbox, Generate from conversations turns visitor questions and agent replies from conversations resolved in the last 30 days into draft Q&A entries (once every 24 hours per site, one AI call per batch); nothing goes live until you approve it.
  2. See which pages prompt the questions. Live chat › Reports lists the top 10 hot pages: the page where the visitor started the chat. A task page with many chat starts needs a clearer guide next to it.
  3. Put the answer where the question comes up. In Live chat › Knowledge base, a pinned Q&A entry appears in the visitor-facing FAQ. Opening the answer does not create a conversation and does not use quota; only Not solved or a request for a person opens one.
  4. Read the effect. The same reports page shows the knowledge base hit rate and the number of conversations. Web analytics › Pages shows views of the guide page itself.
  5. Know the boundary. TapCub does not count your help-desk tickets; bring those numbers from your own system and normalise per 1,000 active users as above. Use enable live chat if the site does not have chat yet.

FAQ

How do you write a user guide?

Start from the questions customers already ask: categorise the last 90 days of tickets and write for the top categories first. For each task, use a title in the user's words, a short "before you start", numbered steps with one action each, a result statement and an "if it didn't work" table. Test with five people who have not seen the product.

What should a user guide include?

A quick start of five steps or fewer, one section per task in a fixed skeleton, a symptom table for problems, links to related tasks and, only if needed, a short glossary. Leave out features nobody asks about; in the sample, four task sections covered 70% of the tickets.

What is the difference between a user guide and a user manual?

In practice the terms overlap. A user guide usually means task-based instructions ("how do I do X"), while a manual can also include reference material such as complete option lists and specifications. What matters is that each page serves one reader need: do a task, learn the basics, look something up, or fix a problem.

How long should a user guide be?

As long as the task needs, no longer. Aim for 3 to 9 steps per task, and split anything longer. Microsoft's style guidance suggests trying to fit all the steps of a procedure on one screen. Readers scan, and one study found they read at most about 28% of the words on a page.

How do you know if a user guide works?

Test it with five people before publishing, and after publishing compare tickets per 1,000 active users for the covered categories against categories you did not document. In the sample, covered categories fell 44.0% while uncovered ones fell 12.5%, so the guide's share was about 31 percentage points.

Sources

Filed underProduct News

Was this article helpful?

We use your answers to fix and expand this page.

Lin Zhou

Product Experience Specialist

Writes about product experience, practical workflows, and growth, turning complex processes into clear steps for everyday decisions.

Find what to write from real questions

Hot pages, handoff reasons and draft answers from resolved chats on the same site and visitor ID as your analytics.

See your data clearly. Find your growth.

Every click, backed by data. Install one line of code and see your first numbers in a minute.

No credit card · Free plans for analytics and chat · Cookieless analytics