How to document tribal knowledge while offboarding employees
If there’s one thing that causes organizational panic, it’s when a person with deep tribal knowledge is about to leave. The panic begins to surface in the final days of that employee’s tenure. That’s when people really face the difficult realization of how much undocumented information is going to just walk out the door without leaving a trace.
The departure of a key employee is the main reason code becomes “legacy.” Despite the implications of the word legacy, it has nothing to do with the age of the code – it’s really about supportability and who knows how to maintain that code. If no one knows how a particular piece of code works, it instantly becomes “legacy.” And this is the main driver for companies to concern themselves with offboarding.
“Offboarding” is the process of capturing the knowledge of an exiting employee so the organization can remain productive without them. In the best case, offboarding captures the proprietary knowledge of an exiting employee and transfers that information into the broader knowledge base of the entire organization.
Companies with strong offboarding capabilities will likely have a culture of ongoing documentation and knowledge sharing. The departure of key employees has more to do with the loss of personality or talent than with information and knowledge.
Onboarding vs. offboarding employees
In my experience, while onboarding and offboarding are reflections of one another and shed light on the importance of documenting tribal knowledge, most companies are still not talking enough about how to do offboarding.
Offboarding is not quite the opposite or inverse of onboarding, but an excellent offboarding process can model a successful onboarding process.
When onboarding a new employee, you want to ensure they know where to find the information they need to be successful, have a plan to go from “newbie” to “knowledgeable,” and know who to rely upon when they need help. When offboarding an employee, your goal is to document what they know so that others can be successful and absorb the newly-documented tribal knowledge.
The offboarding mindset
One way to think about offboarding: the individual who is writing the offboarding documentation is onboarding others with all their tribal knowledge. So the offboarding documentation is effectively the onboarding documentation for another employee.
This can help you approach offboarding differently because offboarding is a mindset.
When dealing with a large codebase or a long-term employee with a lot of domain knowledge, here's one question and action item to start with:
- Question: What do we need to know before this person leaves?
- Action Item: Look at the offboarding employee’s knowledge of their most active code changes and git commits to understand which parts of the code they have taken ownership of.
At Swimm, we prioritize the “why” and de-prioritize the “what” and the “how” in our code. Documentation should focus on why decisions were made that produced the code itself. Let the code explain itself to the developer. Reading code never answers to “why was it done this way.”
Once you know what needs to be documented, create a plan to produce that documentation. The simplest way to do this is to create tickets in your work tracking system (e.g., ClickUp) and assign them to the offboarding employee.
3 approaches to documenting tribal knowledge
The primary goal for documenting tribal knowledge while offboarding employees is sharing knowledge. The issue is that not everyone likes or knows how to document what they know.
Three approaches to documenting tribal knowledge:
- A pair-programming-style approach. Ask the exiting employee questions, and then you document the answers in the way that is most comfortable or helpful. The culling or collecting of this knowledge can always come through interviews and meetings. I recommend recording these meetings. Later on, you can work on post-offboarding documentation writing and review.
- Brain dump. The exiting employee may want to be left alone to write and “brain dump.”
- Swimm’s Platform. Use Swimm’s documentation platform to create code-coupled docs. You can assign a doc to a Swimm user via the Assign link, or assign a doc from a predefined set of reasons (needs review, needs updating, FYI, other) and include an optional note.
Whichever approach you go with, make sure there is enough time to discuss and review everything with employees before they leave.
The motivation factor
The silent factor is motivation. Not every employee leaves on good terms. In those instances, there is likely no way to bring them “onboard” with offboarding.
But in most other cases, employees leave on good terms, and there is goodwill about exiting a company gracefully and graciously. Make sure you have realistic goals and expectations.
Tribal knowledge is a symptom of a deeper issue. The only reason tribal knowledge exists is that there’s either a lack of documentation or insufficient collaborative knowledge-sharing opportunities. When an employee leaves, you are losing unwritten knowledge. The more you leverage documentation and code-coupled doc platforms like Swimm, the less tribal knowledge you’ll have to begin with.
Making documentation a core part of your technical work and delivery processes will make your organization more effective and resilient. Offboarding processes will be about documenting exceptions instead of core functionality.
My advice: if you’re just starting with documentation, identify the most important tribal knowledge and work your way out from there. Identify what’s legacy, look at your code commit changes and who’s making them, and develop an understanding of who owns what parts of your code base. It’s the straightest path to successful onboarding and offboarding.
Swimm’s code-coupled documentation tool can make a huge difference at any stage of documentation maturity. Prioritize documentation for all employees today - so that you have everything in place long before an employee moves on to another opportunity. To see Swimm up close and get started, book a 1:1 demo.