What Makes Good Software Documentation?

The Five Factors that will put your business on the road to success

The main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project. It’s every bit as important as the coding itself when determining the success of a project.

As this article explains:

But what exactly constitutes ‘good’ software documentation? Below we’ll tell you the five best practices that, if used, will ensure your project gets off to the best possible start.

1) It needs to be comprehensive BUT also specific, concise and relevant:

“just enough string to wrap the parcel”

All aspects of the project need to be documented. Undocumented features or gaps are a major drain of time (and money) down-the-line. For E.g. Developers having to read through reams of code to get what they could have found quite simply with properly detailed and documented record-keeping.

On the other hand, excessive documentation and unnecessary repetitions can be almost as big a time-suck too.

Only the most necessary and relevant information needs to be documented. A proper analysis of the projects complexity and needs before development starts should enable you to establish the balance you need here.

2) It needs to be kept up-to-date

Keeping proper documentation can be like a new years resolution – you start off strong and a few months in enthusiasm wanes. It might only mean a few months of unused gym memberships for you, but for your business it can be critical.

It’s best practice to factor maintenance and updates of your documentation into your schedule – even go so far as adding them in as your final step or into your teams ‘definition of done’ checklist.

3) Consider your audience: location, language and layout

When record-keeping it is worth never losing sight of who you are writing for.

Keeping an updated README file with links to the more extensive files at the top helps with discoverability.

Possibly the most important rule of documentation is that it needs to be written as clear as possible, but without making too assumptions about the readers knowledge. This is especially important for the documents written with stake-holder and end-users in mind, steering clear of acronyms or any overly-technical terms.

And with the layout, it needs to be logically-structured and easily searchable, so include a table of contents. Clear headings, bullet-points, and numbered lists help the readers scan through to find what they need quickly, not have to wade through the Dead Sea Scrolls to find what they are looking for.

4) Use cross-links

This is an extension of the best practice layout recommendations above. Whether it’s product pages or user guides, cross-links facilitate quick and easy navigation for the reader, which means quicker and easier understanding.

5) Make it a priority, not an after-thought!

The best thing you can do at the outset of your project is to instil and promote a culture of rigorous, systematic record-keeping throughout your development team. Keep the updates a part of the workflow checklist. Schedule regular audits for outdated information. Consider storing your documentation with the source code (but separated) to help keep it updated and so everyone knows where to find it. Archive previous versions and don’t forget to back-up.

These simple steps, little and often, can help you keep on top of what can feel like a monotonous and fairly thankless part of the job (until you find out you need it!)

‘Good’ can be a subjective term but not here. These are five common-sense, easily-actionable steps that can be the difference between an efficiently-run, successful project and one with a runaway budget chasing it’s own tail.