Software documentation hell, help me!

Good developers and architects know how important it is to have good and up to date specifications of their systems, yet too many fail to accomplish this. Why is that? Well, I think it is too hard to get it right, or maybe we should say, it is not without friction. If it would have been easy then every project would have it in perfect order already. And we all know that is not the case.

The solution to this problem is to make it a lot easier to create good and up to date documentation. It must be almost frictionless to put the information where it should be. If you struggle to find the right spot on the documentation map you rather throw a chat message in Slack leaving all the good benefits of the right context. And there is always a risk that you miss to include vital information or do not explain enough details and risking a misunderstanding and an answer that is built on incorrect information. Instead of taking this risk you should feed the documentation system and benefit from it not only for yourself but also for the whole team. And also make sure that you can benefit from this in the future. This will lead to a positive spiral, when you see the benefits of good information in the right place that is easy to comprehend and all the positive things that this bring to you and your team mates, you automatically will continue putting new information where it should be.

This sounds so easy, doesn’t it? Well, it is not! It is crucial that it is possible to easily grasp the documentation and to always easily find the correct place to put any new information. Only then will this be possible to achieve.

The key to this is that it must be possible to hide information that is in the way to get the big picture but still be there to be found when it’s the details that you need. A good search function is vital of course, but it must not hinder you from seeing the information that might be adjacent to your search terms and crucial for your understanding.

When everybody is on the same page you will notice that you can start to have fewer meetings and still be able to take better decisions.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>