It’s quite common when we reflect on problems that someone will say “we just need better documentation”, and everyone will nod their heads. Yet we rarely ask the question “if we wrote better documentation, would anyone actually read it?”
I recall when I left one company, I was asked to document one particular system that only I really understood. Other people maintained various parts of it but for whatever reason, I was the only one who understood the big picture.
So I wrote up a lengthy document that showed the architecture and common failure points and exactly who to call when they ran across specific problems. I ran sessions where I walked people through this document and answered any questions they might have.
Then I left.
For the next YEAR, I continued to get phone calls “this thing is happening - help us”. In every single case, I was able to tell them the exact page number where this was described in the document.
Was the documentation not good enough? Every single time the answer was in there, and I was able to give them an exact page number.
Or did people really just want the ability to call the expert? Was documentation really not what they really wanted after all?
It’s been my observation that while most teams say they want better documentation, what they really want is for the expert to give them an answer. What they want is tribal knowledge.
There are certainly risks to tribal knowledge; when the experts leave, they take that information with them. Yet, that seems to be what people want. Most people, most of the time, just seem to want to ask the expert.
Note that I’ve deliberately ignored the fact that writing good documentation is a skill, and there is a lot of very bad documentation out there, written by people who didn’t have that skill.
The key is that “writing more documentation” isn’t always the right solution, no matter what we might think in the moment. Will anyone really read it? If they do, will they be able to get the answers they want from it? Or do they just want to ask the expert?
I suspect this is why GenAI is so popular at the moment. It certainly looks like the expert, giving very confident sounding answers, whether or not they’re correct. Where the human expert still wins, however, is that they’re willing to admit when they don’t know.