Writing Down How Your Systems Actually Work

Pick your most important system and ask who you would ring if it stopped at seven in the morning. Then ask who you would ring if that person did not answer. If there is no second name, you have found the problem, and it is almost never the person's fault.

Run the same question over each of your main systems and write the names down. The pattern usually shows one or two people appearing on nearly every line, which is a risk you can now describe to somebody who controls budgets. It is much easier to fund documentation when it is presented as a list of names than as a general good intention.

The uncomfortable version of this exercise is to ask each engineer what they would have to explain if they were away for a month. People answer that question honestly and in detail, because it feels like planning a holiday rather than an audit, and the answers are the table of contents you were looking for.

Do the same for suppliers while you are at it. Which of your systems depends on a company somebody would have to ring, and does anyone know the account number and the name of a human being there. That answer often sits with one person in finance rather than with anybody technical, and it is the sort of thing nobody goes looking for until an outage is already an hour old.

The value is in why rather than what. A settings screen can be read by anybody who has access. The reason the setting is unusual, and the incident that led to it, exists only in somebody's memory. That is the thing worth capturing.

So write the order things have to start in, and what breaks if you get it wrong. The workaround for the known bug the vendor has not fixed. The reason a configuration that looks like a mistake is deliberate. Which supplier to call, the account number, the name of the person who actually answers, and the hours they answer during. Where the licence key lives. What the system does in business terms, so the next person can judge how urgent it is.

A good test for whether something belongs in writing: did it take somebody half a day to work out the first time. If yes, it is worth ten minutes now to save the next person that half day.

Incidents are the richest source. After anything goes wrong, the knowledge is fresh and specific and it evaporates within about a week. Writing the useful parts down while everybody still remembers is the cheapest documentation you will ever produce.

Screenshots of a screen that changes every few months. They are out of date almost immediately and they are worse than nothing, because a reader who sees an interface that does not match stops trusting the whole document.

The vendor's manual, retyped. Link to it and note the version. Step by step instructions for something any competent person can work out in a minute. Anything a script could do instead, because a script is documentation that cannot silently go stale. If the script stops working, somebody finds out.

And resist the urge to document everything before publishing anything. A complete set that arrives never is worth less than six pages on the systems that matter most, available today. Coverage of the important things beats completeness, every time, and the complete version has a habit of never quite being finished.

Watch the middle case too. A long procedure for something done once a year earns its place. A long procedure for something done every morning is usually telling you that the thing itself needs changing. When a page grows to fifteen steps that somebody performs each Monday, the useful output of writing it down is the conversation about why there are fifteen steps rather than the page itself.

The classic failure is a recovery procedure stored on the file server that has just gone down. Or in a system that needs a login that depends on the identity platform you are trying to restore. Or in the password vault behind a sign in that is part of the outage.

So the rule is that documentation must survive the outage it describes. Whatever your main store is, keep an exported copy somewhere independent of it, refreshed on a schedule, reachable from a phone by more than one person. It does not need to be clever. A copy in a separate service, or even a printed folder for the handful of genuinely critical procedures, has saved more mornings than any elaborate arrangement.

One place, not four. The most common state in a business is documentation spread across a wiki nobody updates, a folder on a shared drive, some notes in the ticket system and a few things in an engineer's own files. Pick one home, move it all there, and then be strict, because a second place always starts as a small exception.

Access should be wider than instinct suggests. Documentation read by nobody rots quietly. Keep the secrets separate, in a proper vault, and let the procedures be readable by everybody who might need them.

People do not browse a documentation tree. They paste the words on the screen into a search box, and if nothing comes back they give up and ring somebody. So the words on the screen have to be in the document.

Put the exact error text in. Put the old name of the system in as well, because half the business still calls it that. Put the supplier's name, the product name, the internal nickname, and the name of the thing it replaced. It looks untidy and it is the difference between a document that gets used and one that exists.

Title each page as the question somebody would ask rather than as a noun. How to restart the ordering system in the right order is findable. Ordering system overview is not, and it will be scrolled past by the person who needed it most.

Documentation days do not work. A week is set aside, everybody writes for two days, the material is accurate for a month, and the next one gets cancelled because something urgent came up. The problem is the batching rather than the effort.

Write at the moment of change instead. If a ticket or a project changed how something works, the documentation update is part of that work and the ticket does not close without it. That feels slow the first few times and then stops being noticeable, because the update is small when it happens alongside the change and enormous when it happens six months later.

Trigger reviews on events rather than on a calendar. A supplier changed. A system was upgraded. An incident happened. Somebody left. Each of those makes specific pages wrong, and reviewing those pages is a job with an obvious scope. A reminder to review everything every quarter gets dismissed, every quarter.

The only real test is to hand a procedure to somebody who has not done it and watch them follow it without helping. It is uncomfortable and it works, because every question they ask is a missing line and you will not have thought of any of them yourself.

The best person for this is a recent starter, in their first weeks, before they absorb the assumptions everybody else stopped noticing years ago. They will never be that usefully ignorant again. Ask them to do it for real where it is safe to, and to talk out loud while they do.

The author sitting silently is the whole trick. The moment you explain something out loud, that explanation is lost, and the document stays broken for the next person who tries at three in the morning with nobody to ask.

Do not start at the beginning and work through alphabetically. You will produce a lot of pages about the easy systems and run out of energy before reaching the ones that matter.

Start with the last few incidents, because you know exactly what was needed and what was missing. Then the systems you would most hate to lose, judged by what stops if they stop. Then whatever only one person understands, which you already listed when you asked who you would ring.

Give each page an owner by name rather than by team, because a page owned by everybody is owned by nobody. And accept that some of what you write will be wrong. A document with an error in it gets corrected by the next person who reads it. A document that does not exist gets nothing.