Tyler HawkinsDocumentation is a struggle for nearly every company. When information is undocumented, it remains as “tribal knowledge,” information that someone new to the company must ask others about in order to learn. This may work fine for a time, but what happens when those with the knowledge are unavailable? Or worse, what happens when those people leave the company? The knowledge leaves with them.
Ridding your company of tribal knowledge is difficult in practice, but it can be done in three simple steps. First, document the information. Second, make sure people know where to find it. Third, make sure the documentation stays up to date.
Getting Things Documented
Getting started may feel daunting, so the best thing to do is to just start writing something. Ask yourself what you wish you knew when you started at your company. Or better yet, ask a new hire what they are still struggling to understand or find answers to.
For software engineers, the following topics may be worth documenting:
How do we run our app locally?
What does our release process look like? Are there various environments the code gets promoted to? Do we follow CI/CD best practices? How often does code get deployed to production?
What branching strategy do we use?
What does the code review process look like? Do we have a set of guidelines we all agree to follow?
What version control system do we use?
What browsers and environments do we support?
What does our QA process look like? Do we have dedicated QA engineers, or are software engineers expected to QA their own code?
What browsers or environments do we support? Is our app mobile responsive? Is it a web app, a desktop app, a mobile app, a progressive web app (PWA), or some combination of all of the above?
What are our test coverage standards?
Is our app accessible? Do we comply with any part of the Web Content Accessibility Guidelines (WCAG)? What screen reader / browser combinations do we support?
How do we translate content in our app? What internationalization or localization libraries do we use? Do we work with third-party vendors to translate our text?
How do we track our work? Do we use Jira or Workfront or some other tool? Do we practice Scrum? How long is each sprint? How do we estimate our work? What does a story point represent?
What tools do we use for things like error monitoring, logging, or measuring application performance metrics? New Relic, Sentry, Datadog, Splunk, Sumo Logic, etc.?
What Slack channels should I join? Where do I go to ask certain questions?
How often do we hold 1on1s?
What is the best way to mark time off on shared calendars or submit PTO requests?
What are the core responsibilities of my team? What parts of the app do we own?
What does our app architecture look like?
Document all those things and you’ll be off to a great start! I’m sure you can think of other things that are specific to your organization that are worth documenting as well.
Spreading the Word
Once things are documented, it’s important that people know that the documentation exists and where to find the wiki pages. If people don’t know about the documentation or how to find it, the documentation may as well not exist.
Keeping the documentation all in one place and making your content searchable is probably the most important problem to solve here. Ideally you should use a platform like Notion or Confluence that everyone in the company can access and contribute to.
Keeping it Fresh
If you have existing documentation and people know about it, you’re doing great! The last hurdle to overcome is making sure that your documentation stays up to date.
As time passes, processes change and wikis naturally get out of date. Stale documentation with misleading info is the worst, so finding a good way to keep track of existing documentation and showing ownership in updating it when things change is the problem to solve here.
New hires in this instance are again one of the best resources you have. If a new hire is setting up their app locally and runs into issues when following the setup documentation, they should take the time to update the documentation with the correct steps. If your company is actively hiring, this ensures that fresh eyes will be following and improving the documentation every month.
The same goes for every other current employee. Any time someone finds information in a wiki that is incorrect, they should do their due diligence and update the documentation. Ignoring the bad information won’t make things any easier for the next person who stumbles across the same page. But by taking a few minutes to correct any misinformation when it’s noticed, you make life so much easier for the next person.
The struggle of keeping documentation up to date is more of a people problem than a technical one. Keeping information relevant and accurate requires discipline and a sense of ownership from everyone in the company.
Conclusion
Any time you encounter tribal knowledge, document it. Make sure people know about the documentation. Help create a culture of ownership where updating documentation is something everyone does consistently.
Death to tribal knowledge!
