Every organization has them: the database wizard who built your core systems and is the only person who truly understands them. They know why that one field is formatted that way. They know the workaround for that bug. They know which reports use that hidden calculation.
Then they leave. Maybe retirement, maybe a better offer, maybe an emergency. Suddenly your business-critical system is a black box. This scenario is so common it has a name: the "bus factor"—how many people can get hit by a bus before your project fails? If the answer is one, you have a serious risk.
Why Documentation Gets Skipped
We know documentation is important, so why doesn't it exist? Because the expert is busy building and fixing things. Documentation feels like overhead when there's real work to do. Plus, the expert doesn't need documentation—they understand everything intuitively. The value of documentation is invisible until the crisis hits.
The Documentation That Actually Matters
You don't need a 500-page manual. You need: a data dictionary explaining what each table and field contains, a system architecture diagram showing how components connect, runbooks for common operations (backups, restores, troubleshooting), and documentation of business rules—why things work the way they do, not just how.
The Data Dictionary
Every table and field should be documented: its purpose, valid values, relationships to other data, and any special behaviors. The field "status" with values 1-5 is useless without knowing what each number means. This documentation should live with the database and be maintained as the system evolves—outdated documentation is worse than none.
Business Rules Documentation
This is the most-often-missing and most-valuable documentation. Why is that calculation structured that way? What business requirement drove that design decision? What happens if you change it? The expert knows these things intuitively. A replacement won't, and they'll break things trying to "fix" what they don't understand.
Operationalizing Knowledge Transfer
Documentation alone isn't enough—you need someone who can use it. Cross-train at least one other person on critical systems. They don't need the expert's deep knowledge, but they should be able to perform common operations and know where to look for answers. Rotate who handles issues so knowledge spreads organically.
Building Documentation Into Development
The best time to document is when building. Make documentation part of the definition of done—nothing is complete until it's documented. Use inline code comments for the "why." Use automated tools to generate technical documentation from code. Schedule regular reviews to catch drift between system and documentation.
What To Do When It's Already Too Late
If your expert has already left and you're stuck with an undocumented system, don't panic. Database archaeology is a real service—we can reverse-engineer systems, document what we find, and bring you to a place of stability. It's more expensive than documentation-as-you-go, but it's recoverable. The system isn't lost.
Worried about your database documentation—or lack thereof? Book a free workflow review and we'll assess your knowledge management risk and provide a practical plan for creating documentation that protects your operations.