Many projects struggle with outdated internal documentation or even lack of internal documentation. This topic bothers me very much since there is no fast and easy solution. But let me share some of my experience with knowledge management and try to solve some of the problems I faced.
“Capture, reuse and improve” principle
It is one of the principles of knowledge management.
What does the “capture, reuse and improve” principle mean?
Every time we work on an issue we may try to search in the knowledge base if something that can help us is already exists. If it’s not there we create a new article and capture the knowledge.
The trick is to write it down as we’re doing the work. If we write the article later, we might not remember the important details and it will take extra time to write it. If we take notes during our work, it will take only 10 minutes to clean everything up.
Next time if we face the same situation, we can just open this article again and reuse it. If you see the article is outdated, you can improve it while using it.
Possible problems and how to solve them
Of course, it is not so easy to implement the knowledge management system and there might be many problems. Let’s try to solve them.
“We are too busy to write the documentation”
This is probably the most popular problem. We are too busy with testing, automation, etc to write the internal documentation.
But let me step back and redefine our job a bit. Our job is not to close as many Jira issues as possible and mark them as “tested”. Our job is to provide and control quality. And without proper internal documentation, it might be hard and time-consuming. With the proper documentation, we can help many colleagues to do their job more effectively.
“The documentation should be complete”
In other words, it may mean that the documentation should describe every tiny thing. But in reality, you don’t need it. Good articles get right to the point, resolving the actual problem. Don’t write more than necessary. Think back to everyone’s favorite Stackoverflow site. I bet you immediately look at the answers section, sometimes without even reading the question itself :)
“The documentation should be perfect and we expect good quality of articles”
Good quality is not the same as perfection. Perfection is a bad thing most of the time. You want to aim to be sufficient to solve a problem, not to make articles perfect. Maybe there are typos or even grammar mistakes. It’s fine. When people have a question they need an answer and everything else is secondary.
Perfection leads to delays and backlog.
“We have a big backlog of documentation articles”
If you want to prevent documentation backlog you may want to integrate knowledge management into your work process. You don’t want to give a dedicated time to a person to write an article after his work is done.
If a person takes notes during his work using your knowledge database, the article will be done by 80% when the work is finished. He will need only 10 minutes to clean everything up.
“We are too “lazy” to write articles”
It’s not only about writing articles. It is about every aspect of our work. Even an additional mouse click can make people avoid a workflow or software. Life is too short to spend it clicking here and there. As I described earlier, the knowledge management process should be integrated into the work process. It should be easy and convenient for everyone to use it. Also, you want to have predefined templates, good structure inside articles and in the article tree.
“Our documentation is outdated and I spend a lot of time reviewing all the articles”
You don’t need to review articles to update them. It should be natural. If you go and see that it’s not updated – update it.
If an article is not popular – there is no much sense to update it. The most popular articles are the most up-to-date. If you use the “capture, reuse and improve” principle, this problem is solved by itself almost completely.
“We want to have some articles on specific topics”
Of course, not every article can be done during the work. For such “wanted” articles, you can create an article with a specific structure. So a person who will fill that article knows what exactly to write down.
“Someone asked me to write an article and I don’t know what to write”
The best way is to write down answers in an article while you are answering a question. After all, this is the most important information that people need.
The key principle of knowledge management is to write down your knowledge while answering a question.
“How to maintain knowledge quality”
We tried to solve some problems with knowledge management, let’s focus on how to maintain quality of the knowledge base:
- Don’t leave the next person to deal with a big blob of text. You might want to create templates of most situations, so everyone knows what an article should look like.
- Mentor people who are not very good at creating good quality articles. They will gain knowledge and experience very quickly.
- Check the quality of a little number of articles from time to time. If a person is not good at creating good quality articles, it’s time to mentor him again.
- Every use is a review as well. If you find an article that needs to be updated, then update it while using it.
- Do not make people create some specific amount of articles per week/months/etc. You’ll get the needed amount of junk articles on the last day. Of course, quality of such articles is low.
- Use the “capture, reuse and improve” principle.
Unfortunately, it’s not an easy recipe where you just ask people to write documentation and everything is magically solved. There are many ways when your knowledge management program can become unhealthy.
You need to be consistent and patient. Also you need to choose metrics wisely and influence people by your example.
Which principles do you use in your team? Please, share your experience with me!