Many projects struggle with outdated internal documentation or even lack of internal documentation. There is no fast and easy solution. But let me share some experience with knowledge management and try to solve some of these problems.
Capture, reuse and improve principle
It is one of the principles of knowledge management.
What does that mean?
It means every time we work on an issue we may try to search in the knowledge base if something that can help us 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 and there are many problems. Let’s try to solve them.
We are too busy to write the documentation
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 closing 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 a 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 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 on 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 an article 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 fills that article will know 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 the knowledge quality
We understood how to solve some problems with knowledge management, let’s focus on how to maintain the 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 often situations, so everyone knows how an article should look like.
- Mentor people who are not very good at creating good quality articles. They will gain the 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, the 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 in the comments down below!