Keep it simple stupid, goes also for software documentation!

Are you using more than one tool to handle your software documentation needs? Word, Excel, Visio, Slack, Teams and email etc? Well, then you should probably think again what that’s doing to your efficiency and competitiveness!

There are too many choices these days for documenting a software solution. If the management of a project or a system isn’t the best or is not consistent there is a big risk that team members invent new ways to document requirements, features and architecture during the lifetime of a software system. Developers are often very creative finding new ways of doing as little documentation as possible. This often ends up with documentation in a variety of different formats and in different services. Communication about the systems might be spread out in mail threads, Slack or Team channels or in Skype messages etc.

When it comes to documenting a software solution creativity should not be encouraged. Instead, you and your team will be much more efficient if you can stick to one simple solution that covers the basic requirements of such a system. This includes simple ways of adding content, structure and restructure it, navigate and search it to find what you are looking for. It should also have functionality to put discussions in the right context, next to the feature under discussion, so that all team members can understand why certain decisions are made.

When updating your documentation isn’t without friction you will not do it immediately at the first possible occasion. This leads to information that is old and possibly used in decision making. Keeping software documentation simple and easy to update will prevent your team to find new creative ways of adding specs in new formats. This will be a huge time saver in the long run.

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>