On her first day, Jayne spent a lot of time collecting data from teammates to become familiar with the company’s systems and procedures. Since she appreciated the hands-on approach being taken with getting her settled in, she made her own notes and never stopped to ask if there was a corporate wiki or central document system where this information was stored. Six months later, Jayne had become a valuable member of the team, had gained significant knowledge from her team, and was given a product enhancement project. While reviewing the code for the necessary changes, she noticed some oddly designed features. She asked her team lead, Tim, where the original specification of the app could be found so that she could understand why the application had been written that way. Tim gave her a confused look as said, “You’ll have to talk to Carrie. She’s the only one left from the team that wrote that. I think she’s in DevOps now.”
If you have run into a situation like this then you have already experienced the effects of Tribal Knowledge. This happens when enough people know how something works so it is believed that documenting it would be a waste of time. This common knowledge is ok for situations that everyone must deal with every day, however, relying on it for more obscure information can lead to lost data, increased project time, and decreased morale. Let’s check in with Jayne to see how this plays out.
After learning where Carrie now sits, Jayne heads over to ask about application.
“I’ve been assigned to enhance the shipment tracking system. I’m looking for the original specification, design plans, notes, whatever documentation there is on it and Tim told me to talk to you.”
“Good luck with that. I was only on the team for about two weeks before release and I never saw any documentation. We had meetings where we kicked some ideas around and then we went off and made it work. Josh and Kate were the ones that really knew that system. We’ve been hoping it didn’t break since they left.”
All too often (especially in IT), a source of knowledge will change jobs or companies and that resource will be lost. If the teams rely too heavily on tribal knowledge then it becomes likely that they will fall to the trap of reinventing the wheel or relearning lessons. This cycle results in inefficient use of both time and money. In a worst case scenario, it also depletes the moral of the team members assigned.
The easiest way to avoid the negative effects of tribal knowledge is through documentation. I expect that some people cringed after reading that and/or pictured writing tomes explaining every intricacy. Documentation doesn’t have to be tedious nor does it have to be extensive. Sufficient documentation to avoid a situation like Jayne’s could have been a short comment explaining the unusual approach in the code. Alternately, it could have been kept with the design records in an archive of stories or specifications. The key to good documentation is to eliminate the unnecessary and focus on what is important. Obvious functionality such as basic field validation (eg., number fields do not except letters) can be ignored while business logic should be called out in some way. If a developer needs to come up with a “clever” solution to an issue, there should be a comment in the code to explain why it was necessary and possibly how it works. Whether you write traditional specifications, Agile stories, or take notes in a team wiki, a few minutes of writing can save hours of review and frustration.