Every engineer understands the value of code knowledge management. I doubt many developers repeatedly say to themselves: “There’s too much documentation here.” Yet, most of the existing knowledge management tools do not answer our requirements, and we’re left with tedious, manual processes. As a result, documenting code has become like going to the gym. Once we’re into it, we understand the value, but it’s hard to get us up and running.
As a VP R&D who is co-founding a startup, and a tech lead at Guradicore just last year, I believe knowledge management is at the core of making good decisions and being productive. Here are four requirements I look for when shopping for a code knowledge management tool.
4 code knowledge management tool requirements
1. Covers multiple use cases
A good code knowledge management tool will single-handedly cover a wide span of use cases, from onboarding to code reviews to component installation. To do so, the tool should be able to include tutorials, algorithm explanations, information about why certain technologies were chosen, etc. If these different documentation formats are distributed between different tools, adoption will be scarce and usage will be non-efficient.
2. Available on-demand
Tools like Discord, Confluence, and Notion are useful for managing discussions and projects. They can be used for looking back into why certain decisions were made. But a good documentation tool needs to be able to provide answers on-demand, without the digging (and the time that goes into it).
Developers need to be able to immediately find out what a code line means, why a decision was made, how to install a component, why files are divided the way they are, which research was done on the feature, etc. Trying to find out by retrieving lists from Jira or Confluence does not yield high-quality results. If getting the answers is too difficult or takes too much time, they will not use the tool and go back to asking others or move forward to the best of their understanding.
3. Answers the what and the why
Today, most tools either explain what they did with the code, or why they did it. Code snippets, service contracts, in-line documentation – they all explain what happened in the code. Wikipedias, emails, chats – cover the why. But more often than not, this is not documented anywhere.
To really understand the code and how to use it, our engineers need to understand both what was done and why it took place. Blog posts are a good way to cover this, as they provide technical tutorials and explanations. But they are not scalable in large organizations, and they could also be difficult to find answers in, if they are not structured well. So, we need a tool that shows us the code, and the entire story behind developing it – from design through research and up to programming.
4. Fit for beginners and senior engineers
Too often we think of documentation only for one audience: new developers. More specifically, when they’re onboarded to the company. As a result, we lack the right infrastructure for more senior developers. For example, when they work together on a new feature a service they’re not familiar with. Or when they have to gain observability into dependencies.
Therefore, good documentation needs to be usable and understandable for beginners, intermediate developers and our advanced developers who (think they’ve) seen everything. It should include beginner and advanced explanations, enable high-level and in-depth understanding, and enable integration into existing developer tools.
Finding the right tool
I encourage you to do your research and not compromise on a documentation tool that isn’t right for you. At the same time, do not give up on documenting because you don’t have the bandwidth for it or the right tools. Personally, I recommend Swimm, because it answers all the requirements from above, and more.
…
About the writer: Shay Nehmad is an experienced Team Lead and Tech Lead. He led the Infection Monkey open source project at Guardicore and is now co-founding a new startup, where he is the VP R&D. Prior to Guardicore, he served in the IDF’s 8200 unit for 6 years, receiving an honorary award after leading an R&D team for 2 years.
Learn more about Swimm and sign up for a demo.
