Internal documentation: four kinds that need four different homes

Updated

Companies say internal documentation and mean any of four things, each with a different reader, a different update trigger and a different definition of out of date. Keeping them apart costs one conversation. Merging them produces a single searchable pile in which nothing can be reviewed, because each item in it changes for a different reason.

Answers: belongs in the base

Recurring questions with short answers, updated when the answer changes, owned by whoever would be asked. This is the only one of the four with a same-quarter payoff, and it is the one most often deferred while a taxonomy is designed for all four at once.

Process: belongs with the process owner

How work moves between people, with handoffs and responsibilities. Updated when the process changes, which is rarely and deliberately, and reviewed by the person who runs it. Written differently from an answer because the reader is following it rather than looking something up.

Technical reference: belongs beside the code

How a service works, what it depends on, how to run it locally. It goes stale the instant the code moves, so it belongs in the repository where the same change that breaks it can fix it. Documentation about code in a separate system is documentation that will be wrong within two releases.

Records: belongs wherever retention is answered

Signed policies, approvals, anything with a retention period attached. Judged by whether it can be produced complete on demand, not by whether anybody found it in twenty seconds, and that is an opposite design to everything above it.

The seam between them

A short list of links and a rule about which direction they point: the base links out to the process, the process links out to the record, and nothing is copied. The copy is always the version that goes stale and always the one that gets read, because it is the one with a search box in front of it.

Questions people ask about internal documentation

Can one tool hold all four?

Several claim to, and the question to ask is whether each kind can have its own review rule and its own permissions without ceremony. A tool that treats a typo fix and a policy approval the same way will make one of them unbearable.

Which should a company build first?

Answers, unless something external depends on the records. Answers pay back fastest and the discipline they build, owners and review dates, is what the other three will need anyway.

What about documentation nobody reads?

Delete it and see who complains. A document that has not been opened in a year and whose absence nobody notices was costing you search quality for nothing, and the complaint, if it comes, tells you exactly who the owner should be.

Sources

Related answers

Keep the article library: $29 a monthStart the article library