Stop 7 of 9 · Daily
Documentation people follow
One house style, then onboarding, offboarding and change notes generated from your own ticket history, each line marked confirmed or inferred before anyone follows it.
The documentation problem is a voice problem
Hazem has documentation. It is in four places, written by three people over six years, and none of it reads the same way twice. When an engineer is covering a site at short notice they do not read inconsistent documentation, they call Hazem. That call is what the documentation was supposed to prevent.
Fixing it is not a writing project, it is a template project. Decide the house style once, then generate everything through it, then review. The generation is fast. The review is the job, and it does not get delegated.
The house style file
One file, kept in every client Project, that every documentation prompt attaches. It is short.
| Rule | What it means |
|---|---|
| Console first | Every step opens with where it happens, then what to do |
| One verifiable result | Each step ends with what you should see if it worked |
| Roles, never names | The change approver, not Deborah |
| No client-identifying detail | No addresses, no user names, no case or patient references |
Add your own two or three. The value is that the file exists and every prompt starts by attaching it, so a document written in March and a document written in November read like the same practice wrote them.
[attach the house style file and the last twelve joiner and leaver tickets for this client with names, addresses and case references removed] Build two checklists for Delacroix Contracting, one for a joiner and one for a leaver, following the attached house style exactly. Take the systems and the order from the attached tickets, not from general practice. Mark every line confirmed where the tickets show it happening, and inferred where you are filling a gap. At the end, list the systems that appeared in fewer than half the tickets, since that is where we have been inconsistent. For the leaver checklist, put anything with a compliance clock on it first, with the deadline in the line itself.
The inconsistency list is usually the most useful output. It is a free audit of your own process, and it tends to surface one system that half your engineers forget.
[attach three existing runbooks and the house style file] Rewrite these three runbooks in the attached house style without changing a single technical instruction. Where two of them describe the same task differently, tell me the difference rather than picking one, because one of them may be wrong. Flag any step that has no verifiable result, and any step that names a person instead of a role.
[paste the ticket work log with names and addresses removed] Write the change note for this in the house style: what changed, why, blast radius, what we tested, how to reverse it, and who approved. Then write the two-sentence version for the client portal. If the work log does not say who approved or how it was tested, write those fields as missing rather than filling them in.
The artefact
The house style file, a joiner and leaver checklist pair per client with every line marked and reviewed, and a change note format your engineers fill the same way every time. The leaver checklist with its compliance clocks is the one an auditor asks for by name.