How to Document Tribal Knowledge So It Outlives the Person

Why this matters

Most shops that try to capture what their veterans know end up with a folder nobody opens. The capture happened. The knowledge still walked out the door, because a written thing only outlives its author if it survives three tests the author never applies: a stranger can find it, a stranger can execute it, and someone notices when it goes stale. This is the craft of the artifact itself, done as a routine of the shop rather than a scramble when somebody gives notice. If you are working against a resignation clock, the triage sequence is a different job and lives in its own article.

Step 1: Capture at the moment of surprise, not on a schedule

Sit a veteran down and ask "what do you know that nobody else does" and you will get a shrug. The knowledge is invisible to the person holding it, because to them it is not knowledge, it is just how the thing works. Scheduled capture sessions produce generic material for exactly this reason.

Capture on a trigger instead. The trigger is any moment where the gap between people shows itself:

• A tech solves in twenty minutes what another tech had been on for two hours.
• Someone asks a question and gets an answer that starts with "oh, that model always."
• A job goes sideways and one person immediately knows why.
• Anyone has to phone a specific person to proceed.

That last one is the highest-yield trigger in the shop. Every call that must go to one named person is an uncaptured entry announcing itself. Make it a standing rule that whoever takes the rescue call writes the entry afterward, not the person who made it. The rescuer knows the answer; the caller knows what was confusing, which is what the entry has to fix.

If you skip this step, you get a capture calendar that produces volume and no value, and it will be abandoned inside a quarter because nobody can point at a time it saved them anything.

Step 2: Write to the person who was not there

The single most common defect is an entry written for someone who already knows most of it. It reads fine to the author and to the two people who were on the job. It is useless to the person who will actually need it, who is by definition the person who was not there.

Concretely, that means:

• No unexplained shorthand. If the shop calls a thing by a nickname, put the real name next to it once.
• No pronouns without an antecedent. "Then you back it off until it seats" is meaningless in eight months. Name the component every time, even when it feels tedious.
• Include what you can see. "The fitting behind the panel, lower right as you face the unit" beats "the usual fitting."
• State the starting condition. What state is the equipment in when this entry begins? Powered down? Panel off? Customer present? An entry that starts mid-procedure is an entry that gets misapplied.

If you skip this step, the entry passes every review by people who were there and fails the first time a stranger opens it, which is the only time it matters.

Step 3: Lead with the trigger, not the topic

Findability kills more captured knowledge than bad writing does. A tech in a crawlspace does not browse a folder tree. They search for what they are seeing.

So title and open the entry with the symptom or situation that sends someone looking, not with the component or the correct term. "Unit runs fine for twenty minutes then shuts down and restarts on its own" gets found. "Control board lockout behavior" does not, because the person searching does not yet know it is the control board. That is the whole reason they are searching.

Put the recognizable phrasing in the first two lines. The searcher's vocabulary is the vocabulary of someone who has not diagnosed it yet.

If you skip this step, you build a library that only helps people who already know the answer well enough to look it up by its correct name.

Step 4: Record the reasoning and the ruled-out, not just the steps

A step list transfers a procedure. It does not transfer judgment, and judgment is the part that walks out the door. Three additions do most of the work:

• Why this order. If a step must come before another, say why. "Verify before you replace, because a replacement that fixes it by accident teaches you nothing and you will be back."
• What you ruled out and how. The dead ends are the expensive part. If the veteran checked three things before landing on the fourth, the three are the entry's real content, because the next person will check them anyway unless told not to.
• The cue that told you. Name the specific observation that turned the diagnosis. A sound, a reading against a nameplate value, a pattern in when it happens. "It only does it after a long run" is a cue. "It seemed off" is not.

Where a real hazard is involved, the safety action leads the entry. Gas, water combined with electricity, stored energy, work at height, or a system under pressure: the first line is de-energize and verify dead, isolate and relieve pressure, evacuate, whichever applies. A veteran's captured shortcut that quietly skips lockout is worse than no entry at all, because it carries their authority and a newer tech will follow it.

If you skip this step, you have written a checklist, and the first case that differs slightly from the checklist puts the reader right back on the phone.

Step 5: Name the boundary conditions

Every piece of shop knowledge has an edge past which it is wrong. The veteran knows the edge without thinking about it. The reader does not, and will drive straight past it.

Close the entry with two short lines: when this applies and when it does not. Age of equipment, residential against commercial, a specific configuration, a jurisdiction. The version without boundaries is the version that gets misapplied confidently, which is more dangerous than not having it.

Step 6: Store it where the work happens

An entry in a shared drive folder is an entry with one more click than a tech under time pressure will spend. Attach it to the thing it is about: the job type, the equipment record, the customer account, the checklist step where it comes up. If your system supports linking a knowledge article from a job template, the entry should surface when that template is used, without anyone remembering it exists.

The rule of thumb: if finding it requires knowing that it exists, it will only be used by people who already knew the answer.

A worked example: the intermittent shutdown

A shop notices the same fault type keeps landing on the senior tech. Pull the last five tickets of that type. The senior tech closed his in about 0.4 hours. The other four, handled by three different techs, averaged 2.6 hours. That is a 6.5x spread on the same fault, and it is being paid five times a year.

Capture runs like this:

The senior tech gets a fifteen-minute recorded phone call the next time the fault comes in, describing what he is looking at and why, while he is looking at it. Call it 25 minutes of his time including the setup. The lead tech then writes it up and runs the cold test in Step 7, roughly 40 more minutes. Total invested: about 65 minutes, a little over an hour.

The draft entry initially reads "check the safety circuit." The cold test kills that in ninety seconds, because the reader asks which safety circuit and where. The rewrite names the component, its physical location, the starting condition (power off, panel removed), the specific reading to compare against the nameplate, and the two things the senior tech had already ruled out on his way there, with the observation that ruled each one out.

After the entry is live, the next four occurrences by non-holders average 0.9 hours. Against the prior 2.6, that is about a 65% reduction. It is still 2.25x the senior tech's 0.4 hours, and that residual is honest: the entry transfers the path, not twenty years of pattern recognition, and expecting it to close the gap entirely is how people conclude documentation does not work.

The payback: 1.7 hours saved per occurrence, five occurrences a year, is 8.5 hours a year against about 1.1 hours invested. Roughly 8x in the first year, and the entry keeps paying in years two and three for zero additional cost.

What would change this calculation. If the fault came up once a year instead of five times, the payback stretches past a year and the entry is still worth writing but drops down the queue. If the equipment line is being phased out of your customer base over the next eighteen months, do not write it at all; document the replacement decision instead. Capture effort follows frequency multiplied by remaining life, not how impressive the knowledge is.

Step 7: Run the cold test before you call it done

This is the step that separates a library that works from a folder that does not. Hand the finished entry to someone who was not on the job and who would plausibly need it, and have them read it aloud and narrate what they would do. Do not answer questions. Every question they ask is a defect in the entry, and you fix the entry rather than the reader.

Budget ten to fifteen minutes. A first-draft entry typically generates three to six questions, and about half of them are the author's shorthand.

The stronger version, for anything high-frequency: have the cold reader actually perform the task from the entry alone on the next real occurrence, with the author present and silent. If they complete it without asking, the entry is done. If they ask once, the entry has one more revision in it.

Step 8: Give every entry a review date and a retirement

Documented knowledge rots quietly. A supplier changes a process, a code cycle updates, an equipment line ages out, and the entry keeps sitting there looking authoritative. Wrong documentation is worse than none, because it is trusted.

Stamp every entry with the date written and the author, and set a review interval by volatility: anything tied to a supplier process, a permit workflow, or a code requirement gets an annual look, because those change on someone else's schedule. Anything tied to how a piece of equipment physically behaves can go two or three years. When an entry is reviewed, the reviewer either re-stamps the date or retires it. Retiring is a legitimate outcome and should be as easy as writing.

Tie the review to something that already happens annually so it does not need its own discipline. The slow season, or alongside the skills review.

How to verify the program is working

• Track rescue calls by topic. The metric that matters is not how many entries you have written, it is how many times per month someone still has to phone one named person. If that count is not falling, you are writing entries nobody can find or use.
• Audit findability quarterly. Pick three entries at random, describe the underlying situation in a tech's words to someone who has not read them, and watch whether they surface it in under a minute. If they cannot, the problem is Step 3, not the content.
• Check the age distribution. If nothing in the library has been retired, the review step is not really running, and you are accumulating confidently wrong material.
• Read your newest five entries against the naive-reader test. Unexplained shorthand creeping back in is the earliest sign that the cold test has quietly been dropped because everyone is busy.

References

• OSHA general industry standards on documented procedures for hazardous work
• U.S. Small Business Administration (SBA), guidance on operational documentation and continuity
• See related: Capture Tribal Knowledge Before a Key Tech Leaves
• See related: The Single Point of Failure Audit for Shop Skills
• See related: How to Build Training Material With the Tools You Have