Your documentation sucks… but it doesn’t have too
Your documentation sucks… but it doesn’t have too
How to re-think Engineering Knowledge Management
Every week, how much time do you think a developer spends trying to find answers to questions? A recent study found that they spend around 7 hours per week looking for information. Almost one day per week!
But that’s not the worst of it…
The same developers also waste around 9 hours additional hours of your organizational experts time to get their questions answered. Ok, now for every developer, every week, they are wasting two full days to get questions answered.
But wait! That’s still not the worst of it…
The worst part is that around 40% of those questions are redundant. To state that a little differently, the developer should have been able to find their answer via some kind of documentation. So why is it so hard to find the information they need to get their jobs done?
The major culprit is that we look at documentation as a singular problem. We have boiled it down to “just needing to write things down so that other people can find it” without much of a plan, process, or governance. Don’t get me wrong, documentation is hard… no doubt about that, but we need to think about this problem a little differently
Documentation ≠ Knowledge Management
Knowledge Management is a deliberate focus on improving documentation of specific kinds of knowledge and providing them back in a clear, concise, and easy to access manner. When you think about documentation as a knowledge management problem it becomes very clear that this is more than a singular problem. It’s many problems for many different people and requires different systems for each.
I try and break this down into three major categories, but there are definitely subsections under each of these.
Documentation of a tool, service, or technical artifact
As the owner of an API or anything that needs versioning, its important to keep my documentation up to date and in context to the supported versions. It would also be great to release documentation alongside the code. Nothing is worse than going through a major release, and then have to go and update a bunch of documents in Confluence.
In a perfect world, this type of documentation could be delivered along side of a catalog using a documentation-as-coded product. It would be even better if you could find this information, along with other details, inside of a developer portal.
Documentation of a business process, group, or product
There are many other things across an enterprise that need to be documented in one way or another. This could be product, process, or organizational information but would be primarily business focused. This is where tools like Confluence can really shine. There is no need for version control with most of the updates coming from business analysts or product managers.
Getting a question answered
This is always the tricky one… Where do I go when I need some help? This is pretty well described above, but most companies I have worked with really don’t have this problem solved. There was the old way of doing it like StackOverflow but that has its challenges until there is a significant number of questions answered.
Back to the example
Let’s look a bit deeper into the example from the beginning in context of these three different areas.
If I am a developer, and I need to get a technical question answered, then I might spend 15-20 minutes digging through a tool like Confluence to try and find the answer to the question that I have. There are two possible outcomes here, I find “an answer” to the question I have or I can’t find anything.
The reason I say “an answer” is that its hard to tell what can or can’t be trusted. Does this information take into account the newest version of this APIs documentation? Or maybe I haven’t migrated to the newest version, is this about the right version? Sometimes its really hard to tell with the chaos that can come from an unmanaged knowledge tool.
How can you fix this?
If you look at this through a different lens, there could be a very different outcome.
Instead of using a singular tool like confluence, you could have multiple other solutions in the mix. A documentation-as-code tool that is included in developer portal and a question & answer forum.
Now the it becomes much easier for the developer having the question. The API documentation is now associated with a given code version which makes it much easier to trust. If they still don’t understand or trust that documentation, they can go to the Q&A solution to search for others who had a similar question.
This now memorializes the questions for the future and can help the team to improve their documentation.
What was that? What about AI coming to make this problem go away?
There are some really great AI tools out there that can help with some of these problems. BUT… they are not magic. I did get a chance to talk to the Unblocked folks last week at LambdaConf and what they have put together really does seem like magic.
I am very, very impressed with this tool so far though I have to say that I have not used it in the wild yet. It has connections into your Github, Confluence, Slack, and more. It can find information across these connections and provide an answer for many different types of questions. This includes questions around the code itself or more operational questions.
This doesn’t mean that you can just ignore the mess you already have.
Leveraging Unblocked would be a great way to get started and help developers, or others, find the information they need to get their job done. But, this does not mean the job is over.
Without looking to structure your data, the tools used to capture it, and extending out its data model, there will always be gaps. You would just be making better documentation and not managing the knowledge of the company.
Regardless of how good Unblocked does derive questions out of chaos (and it does seem to do this really well). You will always get better answers with better data under the hood.
Product thinking is required
You have to think about Knowledge Management as a product, or multiple products, inside of your organization. To manage any of these products you really need:
Baseline metrics to show waste and friction across the ecosystem
Qualitative sentiment scores for how well these products are working
Value based analysis that is brought from these products
Continuous improvement culture
By using good product thinking and solid analysis you can really make a sizable impact to an organization.
Conclusion
There is a ton of waste across your organization attributed to bad documentation and knowledge management. You should be deliberate in your efforts to solve these unique challenges. Taking this different approach can have a major impact over time and can have a significant impact on overall productivity.
Your developers will thank you.
Note - For everyone who made it reading this far and found joke in the title. Thank you for all of the funny responses. For others that didnt catch it, it should be “to” not “too” in the title. This is a great example of how documentation, even under the best of circumstances, can easily be wrong.