You might be surprised on your first week of work to be met with either a bunch of documentation links that point you to dozens of other confusing wiki links, documentation that is stale and out of date, or even a general lack of documentation all together. In general, it seems that without strict guidance and upkeep, documentation is often treated as a second class citizen a lot of the time. It is precisely this mentality that leads to a frustrating onboarding experience for either a new employee starting their first day on the job or a seasoned employee learning a new system. Great documentation doesn’t only smooth the onboarding experience for new developers; it is also helpful for seasoned veterans who need a quick glance. Our brains work in such a manner that they can only hold so much information before old information is stored away in the archives to make room for new information that can be recalled on a dime. I’m here to argue that domain knowledge should not be considered tribal knowledge.
Struggle to finding documentation
One of the problems many organizations with long tenure face is that documentation is plentiful, but good documentation is sparse. For example, you might find yourself searching for a fictional System A in this example. System A is a large system that has existed in its domain for a few years and has seen plenty of retention in its lifetime. You open up your company’s database of information and search for “system,” and it looks a little bit like this.
Wow, that is a lot of results! You continue to spend time scouring through each result, finding documentation articles written anywhere from as recent as a few months ago to as old as a few years ago and written by a deactivated user account. You’ll find yourself spending precious time navigating through this sea of results, where half of the articles are related to System A, but aren’t the documentation you are looking for. The fragmentation of documentation creates a web of problems that leads to frustration.
This issue is frequently represented by a sparse, loosely connected graph of nodes representing documentation written over time and loosely connected.
The problem illustrated by this visualization is that searching the documentation for the information you seek is complicated due to the large number of results, where each document outlined in a circle may or may not be connected to or related to the dozen results returned by the search result set.Not only are the results hard to navigate, but the results are cross-domain and might not entirely be relevant for the piece of information you are looking for.
One way to combat this is to assume that if documentation hasn’t been updated or viewed in over a year, it is probably no longer relevant, provides minimal to no value, and should be archived. Stale documentation leads to this complicated, unconnected graph of documents that, if not maintained, muddies the result set with useless information over time.
Organization
A different way to help with this problem has to do with how documentation is organized. Imagine instead of a loosely connected, partially unconnected graph that spans different project domains, each article of documentation has a specific domain it belongs under, and each domain has a “landing zone” page that connects the rest of the documentation in a tree-like view. Users can easily navigate the system and information they are looking for from this landing zone.Each level of documentation is connected and can be easily found in a centralized location. In the previous example of a user searching for documentation on System A, it could be viewed loosely as the following:
In this diagram, the user knows the domain of System A in the left-hand box and can navigate to the top-level “landing zone” for information about System A for that domain. From that page, they can navigate down each level of the tree to find corresponding information about System A for whatever topic they are looking for. Similarly, in the domain on the right side for System B, if there is documentation that relates to System A and how it interacts with System A, it should live in System B’s domain.
While this organized idea is flawed and works in a “perfect world,” the overall theme is that documentation must be organized in order for it to be easy to find and follow. When you go to create documentation, instead of creating new pages sprinkled throughout the database, first stop and think and ask yourself, “Does this documentation live in a domain, and is there already a central domain I can organize this under?”
Documentation takes effort!
In order for documentation to be well maintained and organized, it takes an organized effort from all individuals involved. Especially when documentation is shared across the team and is not managed by a dedicated team of technical writers or project managers.Documentation should be treated as a first-class citizen. While there is a high upfront cost to putting effort into documentation, the future results pay dividends that will outlive employees and help onboard employees for years to come.
Ways to combat poor documentation
Every person should feel empowered to add documentation where they see gaps in the process. Documentation should be encouraged, prioritized, and rewarded so that it becomes a first-class citizen. Every time you stumble on some documentation that is lacking vital information or missing, take the time to document it. Others in the company will likely go down the same path and struggle the same way you did. The collective and summed efforts of the entire team taking ownership of documentation exceed what a single individual can achieve.Own your team’s documentation and avoid this tribal knowledge that is passed around through long-tenured employees.
Easy examples are that every repository should have a README.md file that outlines the repository, the context, and any necessary documentation. Documentation that lives in source control is easier to manage than documentation that may be stored on a network or file share that is less likely to be accessed. It shouldn’t be difficult to find documentation for a project.
The Impossible
While good documentation may appear to be an impossible juxtaposition and that these ideas only work in a perfect world, decide to own your team’s documentation and make it a collaborative first-class citizen as part of your project-work rituals, and I promise you will notice a significant improvement. Documentation will never be perfect, but treating it as a first-class citizen, maintaining and archiving out-of-date, unreliable information, and putting in an effort to organize and maintain a means of organizing will significantly improve the developer and employee experience in your team.