In-App Help Documentation That Ships With Every Feature

Every system I build has a Help panel on every page, and the text in that panel lives in the codebase, in the same folder as the page it describes. That is what I mean by in-app help documentation: short, practical instructions that sit inside the software, next to the screen the user is looking at, rather than in a manual filed somewhere else. The rule I work to is plain. If a page changes, its help changes in the same piece of work. Not next month, not when somebody remembers.

That rule sounds small. In practice it decides whether your organisation owns the system or the system owns you.

Why does software documentation always go out of date?

Because it usually lives somewhere else. A Word file on a shared drive. A PDF emailed once at launch. A set of screenshots taken on the day of training, before three rounds of changes happened.

The screen gets updated because a user asked for it. The manual does not get updated because nobody is looking at the manual that week. Six months later the manual describes a button that no longer exists, so people stop trusting it, so nobody maintains it, and now the only real documentation is a person's memory.

That person then goes on leave, or takes another job, or moves abroad. In a small country this happens more often than people plan for. The organisation is left calling the developer to ask what a field means, and paying for the privilege.

What in-app help documentation looks like in practice

In every product I run, each page carries a Help panel. The content is written for the person doing the task, not for a programmer, and it answers a short list of questions:

• What is this screen for, in one or two sentences.
• What does each field mean, especially the ones with rules behind them.
• What happens when you press the main button, and what it changes elsewhere.
• What to check first when the result looks wrong.
• Who is allowed to do this, and what a different user role would see.

In Scholar, my school management system, that means a new office clerk can open the enrolment screen in the middle of term and read what the fields do without waiting for the person who was trained in August. In Mortgage Base, my loan servicing platform, it means the help beside a payment posting screen explains how the posting affects interest and principal, because that is the question staff actually ask.

The content is short. Two or three paragraphs per page is usually enough. Long help goes unread.

How do you keep help in sync with the code?

Two mechanics, both boring, both effective.

The same-change rule

When I change a page, I change its help in the same change. The help file sits beside the page file in the codebase, which is the collection of source files that make up the software. Opening one means seeing the other. There is no separate task to forget and no separate document to lose track of.

An automated test that refuses to let help go missing

I also run an automated test, a small programme that inspects the software and reports a failure if something is wrong. In my admin systems, that test walks every administrative page and fails if a page has no help entry. If I add a new screen and forget the help, the test tells me before the work is considered finished.

This is not clever engineering. It is a tripwire. The point of a tripwire is that it works on the day you are tired.

Does in-app help actually reduce support requests?

It does, and the pattern is consistent across the systems I operate, including Scholar, my HR and payroll system EasiMan, Mortgage Base and the administration side of Direct Belize, my hotel booking platform.

The questions that disappear are the small repeated ones. What does this status mean. Why is this field locked. Which report do I run for the board. Those questions are cheap to answer once in writing and expensive to answer twenty times by phone.

The second effect matters more to owners and managers: staff turnover becomes survivable. When the person who knew the system leaves, their replacement has something to read that matches what is on the screen today. The organisation does not depend on my memory, and it does not depend on one employee's memory either.

In-app help compared with a traditional user manual

Both have a place, but they fail in different ways.

• A separate manual is good for policy, narrative and training sequences. It goes stale because updating it is a different job from updating the software.
• In-app help is good for the question being asked right now, on the screen being used right now. It stays current because updating it is part of the same job.
• A manual is read once, usually during training, usually by people who are nervous.
• In-app help is read at the moment of need, by someone who already knows what they are trying to do and is stuck on one detail.
• A manual needs someone to find the latest version. In-app help is always the latest version, because it ships with the feature.

I write help into the product first. If an organisation also wants a training booklet, that is a reasonable extra, but it should not be the only documentation holding things together.

What else ships with the work

In-app help is one of four things I hand over on every project, alongside the source code, which the client owns.

1. A handover document. What the system does, how it is structured, what depends on what, and what to know before changing anything.
2. A runbook. A step by step guide for routine operations: backups, restarts, certificate renewals, what to check when something looks slow, and who to call.
3. A changelog. A dated list of what changed and when, so a manager can see the history without asking.
4. The in-app help itself, maintained in the codebase and checked by tests.

For public bodies this matters even more than for private firms, because staff rotate and institutional memory is thin. I have written separately about what a serious digitisation programme in the public sector needs, and documentation that cannot drift is near the top of that list.

A checklist before you commission software

Whether you work with me or with somebody else, ask these five questions before you sign.

1. Where does the help text live, and who updates it when a screen changes?
2. Is there anything in the build process that fails when documentation is missing?
3. Do I receive the source code, and do I own it?
4. Will I get a runbook that lets another technical person operate the system without the original developer?
5. If the developer is unavailable for a month, what breaks, and who reads what?

If the answers are vague, the real documentation is a person, and you are renting that person indefinitely.

Where to start

If you are weighing up custom software, a hosted product or carrying on by hand, a few practical first moves:

1. List the three screens or tasks that generate the most questions from staff today, even in your current manual process.
2. Ask whoever supports your existing systems where the documentation is, and open it. See whether it matches what is on screen.
3. Write down what should happen if your most knowledgeable staff member were unavailable for a month.
4. When you request a quotation, put documentation, handover and ownership in the scope in writing, not as an afterthought.
5. Expect help text to take a modest share of build time, a few hours per significant screen, not most of a week.

If you would like to talk through what this would look like for your organisation, you are welcome to get in touch.