Most internal tools are documented twice. The first time is at launch, when someone writes a long document that is accurate for a few weeks. The second time is never. When the person who built or looked after the tool moves on, the successor finds a manual that describes a system that no longer exists.
This article is for the developer or head of technology who wants documentation that survives a handover. It is about the content of the documents. For the question of who owns the tool, see who owns an internal tool after its author leaves.
Why two pages
A limit of two pages forces choices. You cannot describe everything, so you describe what a new person needs on the first day and in the first month. Everything else lives in the code, the tickets or the team's heads, and it is fine to say so.
The split is by purpose. The first page, the run sheet, is for the person who keeps the tool going from day to day. The second, the maintenance sheet, is for the person who changes it. They are often the same person, but they open the pages at different moments and with different questions.
Page one: the run sheet
The run sheet answers "what do I do when something happens?" It should hold:
- What the tool is for. Two sentences: who uses it, which task it supports, and what stops if it is down.
- Where it lives. Address, hosting, and where the logs are. Do not paste passwords; say where they are stored and who can grant access.
- Routine jobs. What has to happen daily, weekly or monthly, such as a data import, a backup check or a user list review.
- Known problems and their usual fix. The three or four things that go wrong most often, each with the first step to try.
- Who to call. The owner, a deputy, and the supplier or vendor contact if there is one, with the situation in which each is contacted.
- How users get help or access. One line is enough.
A good test is to ask someone who has never seen the tool to follow the page when a user reports that "it does not load". If they can reach the right first step, the page works.
Page two: the maintenance sheet
The maintenance sheet answers "how do I change this without breaking it?" It should hold:
- How it is built. The main parts and how they connect, in a simple list or a small diagram. Name the language, framework and database, and the other systems it talks to. For an AI-based tool, a similar structure is described in what a new team needs to take over an AI agent.
- Where the code is and how to run it locally. Repository location, the steps to start a working copy, and how to run the checks, if there are any.
- How a change reaches users. The steps from a finished change to the live system, who may do it and how to go back if it fails.
- Dependencies with a deadline. Certificates, licences, external services or software versions that need attention on a known date.
- Decisions that look strange. Two or three places where the tool does something unexpected on purpose, with a sentence on why. This saves a successor from "fixing" something that was deliberate.
- What is not finished. A short list of known gaps and planned changes.
Write for the person who takes over
Documentation written by the author tends to skip what feels obvious. Ask someone else to read it, ideally the person who will inherit the tool, and note every question they ask. Each question is a missing line. Write short sentences, use the words your team uses, and prefer a concrete step over a general description.
Who updates it and when
Each page needs a named owner and a date on top. Put the owner's name and the date of the last review in the first line, so nobody has to guess.
Link the update to events that already happen. When a change goes live, the person who made it checks whether either page needs a line. When someone leaves or joins the team, the owner reads both pages again. Add a review once or twice a year in the calendar as a safety net, not as the main mechanism.
How to tell the documentation is stale
You do not need to read every line to notice that a page has aged. Look for these signs:
- A step refers to a screen, command, address or person that no longer exists.
- The review date is older than a year, or there is none.
- Someone solved an incident without using the page, because it was faster to ask a colleague.
- The list of known problems is empty although users report problems.
- The page describes a version of the tool that is no longer in use.
One honest check helps more than any rule: once a quarter, pick one routine job and let someone follow the run sheet exactly. Whatever they could not do is the list of corrections.
When two pages are not enough
Some tools are large, regulated or shared across many teams, and two pages will not cover them. Even then, keep the two pages as the entry point and link to the longer documents from them. The short pages are what people will actually read when something is wrong.
What to do this week
Choose one internal tool that depends on a single person. Ask that person to write the run sheet in one hour, using the list above. Then ask a colleague to read it and mark every unclear line. Add the owner and the date, and put the maintenance sheet on the same list for next week.
Sources
- Our related article linked above.
- The two-page structure, the contents of each page and the signs of stale documentation are a general working approach, not a standard; adapt them to your own tool and team. No figures or client results are claimed in this article.