Designing a Clear Help Page
Sooner or later every project needs a page that explains how to use it. The order of that page matters more than its wording, and good models can be found well outside software.
The reader arrives with a problem
Nobody opens a help page for pleasure. The reader has tried something, it has not worked, and they would like to be elsewhere. That fact should shape every decision. A help page is not the place for the history of the project or for a tour of every feature. It is a place where a person in a mild hurry finds the one thing they need and leaves.
Technical writing as a discipline starts from this same point: decide who the reader is and what they are trying to do, and let that choose the content.
Order by what people do, not by how the code is built
The most common fault in a beginner's help page is that it mirrors the structure of the program. The author knows the code is divided into modules, so the page has one section per module. The reader does not know or care about modules. They have tasks: install it, run it the first time, change a setting, recover from an error. Organise the page around those tasks, in roughly the order a new person would meet them. Deciding what goes where, and under which label, is the craft known as information architecture.
Steps are numbered, conditions are stated
When the reader must do things in order, use a numbered list with one action per step. Start each step with the action itself. If a step can go wrong, say what the reader will see when it has gone right, so that they can check before moving on.
Just as important are the conditions: the things that must be true before the steps will work. A required version, a necessary permission, a limit on size. Put these before the steps, not after. A reader who learns at step six that they needed something different at step one has been badly served.
Borrow structure from somewhere unrelated
A useful exercise is to study how help pages are ordered in a field you know nothing about, in a language you may not read well. Because you cannot be carried along by the subject, you see only the skeleton. One example of the pattern is a Traditional Chinese information site about one gaming brand (YS娛樂城), which sets out the conditions attached to a trial credit, walks through a withdrawal as a step-by-step tutorial, and keeps a digest of player comments apart from both. I am not suggesting anything about the subject, and a single-brand site is not a neutral reviewer of that brand. What is worth noticing is purely the arrangement: conditions in one place, a procedure in numbered order, and opinion clearly separated from instruction. A help page for a small command-line tool can use that same three-part skeleton.
Questions that are really asked
A list of frequently asked questions, or FAQ, is worth having only if the questions are real. The test is simple: has anyone actually asked this, in these words? Invented questions, written to show off features, waste the reader's time. Collect real questions from messages and bug reports, phrase each the way the person phrased it, and answer in the first sentence. Explanation can follow for those who want it.
If the same question keeps arriving, treat it as a bug report against the main instructions. The lasting fix is to repair the step that confuses people, not to grow the list.
Write so it can be scanned
Readers of help pages scan first and read second. Help them.
- Headings that name the task: "Change the output folder", not "Configuration".
- Short paragraphs, with the answer before the reasoning.
- Exact text for commands and messages, set apart so it can be copied.
- The same word for the same thing every time.
That last point is easy to overlook. If the page says "folder" in one place and "directory" in another, a careful reader will wonder whether two different things are meant. Pick one term and keep it.
Show the error messages
People search for the exact words on their screen. If your tool prints a particular message when a file is missing, include that message, word for word, in the help page next to its cause and its remedy. This one habit makes a help page far easier to find and to use.
Test it on a newcomer
You cannot judge your own help page, because you already know what it means. Ask someone who has not used the project to follow it while you watch and say nothing. Each place where they hesitate is a place to fix. Do this once and the page improves more than it would from any amount of rereading.
Date it and keep it current
A help page that describes last year's behaviour is worse than none, because it is trusted. Note when the page was last revised, and when the program changes, update the page in the same piece of work.
Working rule: conditions first, then numbered steps, then real questions. If a reader must scroll to learn whether the page applies to them, reorder it.
Last revised 2026-11-20 · Wendell Arkwright