Document This Fix or Just Tell the Crew: Decision Tree
Why this matters
You just solved a problem or found a better way to do something. Now comes a small decision you make dozens of times a month, usually without thinking: does this lesson go into writing, or is a word to the crew enough? Get it wrong in one direction and you bury the shop in documents nobody reads, so the important ones drown. Get it wrong in the other and a hard-won lesson lives in one person's head until they forget it or walk out the door. This tree right-sizes the capture so the effort matches the value.
Start here: will this lesson be needed again when the person who learned it is not around
That single question does most of the work. Documentation exists to move a lesson across time and across people. If neither gap applies, you do not need a document.
- If the lesson only matters right now, to the people already in the loop - a heads-up is enough. Telling works fine when the information is fresh, small, and the audience is present.
- If the lesson will be needed later, by someone not in this conversation - a new hire, the next crew, yourself in six months - it has to be written, or it is gone.
Everything below refines that call.
Branch 1: how high is the cost of getting it wrong again
Weigh the downside of the lesson evaporating.
- If repeating the mistake is dangerous or expensive - a safety step, a sequence that prevents damage, a spec that is easy to get wrong - document it, even if it feels obvious today. Obvious-to-you is not obvious to the apprentice you hire next year.
- If repeating it is a minor annoyance - a small time waster, a preference with no real stakes - a verbal note is usually enough. Not every improvement earns a permanent entry.
Branch 2: how often will this come up
- Recurring situation (every install of this type, every job at this kind of site) - document it, because the payoff repeats every time and the written version stops depending on who remembers.
- Rare or truly one-off - tell the people involved and log it in one line so a pattern can surface later if it turns out not to be one-off after all. Do not build a full procedure around something you may never see again.
Branch 3: is it a fact, or is it a whole method
- A single fact or a one-line rule ("this valve is reverse-threaded," "this customer's gate code changes monthly") belongs in the relevant record where someone will hit it at the right moment, not in a training binder they will never open.
- A multi-step method or a changed process belongs in the checklist or the standard procedure it modifies, so it actually changes how the work gets done and is not just filed away as a note.
Documentation only works if it lands where the reader already looks. A lesson written in a place nobody visits is not documented, it is hidden.
The comparison
| Factor | Just tell the crew | Write it down |
|---|---|---|
| Who needs it | People present now | People not here yet, or future you |
| Cost if forgotten | Minor annoyance | Safety event, damage, or repeat callback |
| How often it recurs | Rare or one-off | Every job of a type |
| Shape of the lesson | Small fact, in-the-moment | A method or a process change |
| Shelf life | Days | Months or years |
| Where it goes | Huddle, text, quick word | Checklist, SOP, or the job record |
When several factors point to writing, write. When they point to telling, tell. The middle case - real but small - gets the cheapest durable capture: one line in a shared log, not a new document.
Watch for the two failure modes
- The over-documenter turns every fix into a memo. The binder swells, nobody can find the five entries that matter among the five hundred that do not, and the whole system loses credibility. If you would not read it a year from now, do not write it as a formal document.
- The under-documenter keeps everything in their head and calls it experience. It works until they are on vacation, out sick, or gone, and the lesson leaves with them. If the shop would stumble without you in the room, that is your documentation backlog talking.
The recap
- Ask if the lesson is needed later or by someone not present. If not, tell and move on.
- Document anything whose repeat is dangerous, expensive, or recurring.
- Match the format to the shape: a fact goes in the record, a method goes in the checklist or SOP.
- Put it where the reader already looks, or it is not captured.
- Avoid both extremes: the memo for everything and the head-only expert.
The judgment to bank: writing costs a few minutes once; a lost lesson costs the same mistake on a loop. Spend the minutes when the lesson has a future.
References
- Trade-standard practice for standard operating procedures and knowledge management
- See related: Capturing a Lesson So It Outlives the Person Who Learned It
- See related: Write a Checklist That Actually Gets Used; The Checklist That Grows Every Time Something Goes Wrong