The state of software documentation needs to improve because it is, bluntly put, not very good. The amount of software that gets written and released every month for public use is phenomenal. It is now an accepted norm to write automated tests that are supposed to increase the software user’s confidence in the product. An important thing that is, in the majority of cases, key to the success of the software creation, is for its potential users being able to understand the purpose of its existence and how to use it. This is gained through reading software documentation.

Some software authors produce sparse documentation on purpose in order to motivate users of their products to purchase consulting services. The rest of software authors who produce something, e.g. a software library, a component, etc. to share with the world, presumably do so to help other developers around the world, and to build their own reputation, perhaps. I applaud this act of generosity. When I mention it to people who don’t live in the software world, they are generally surprised that people, sometimes whole organisations, are so generous with their time and money.

Not every such contribution will live a famous life. To improve the chances of success, and knowledge that the time spent has been invested well, it is important to describe the context, the intended purpose of the creation, and how to use it.
How many times did I search for something or come across a piece of software in some repository (github, npm, etc.) only to find vague sentences in the readme software documentation that left me wondering whether it is worth investing more time into finding further details.

I assume that if you’re creating and releasing something for public consumption, you are mostly fuelled to do so with a motivation to help others. Consider, however, that you might actually be achieving the opposite – that people are wasting their time in large quantities trying to understand whether your product is a suitable fit for their needs, and how to make use of it.

I personally dislike spending time on re-inventing the wheel. Which is why I frequently search for pieces of software, and it often is a rather painful experience, I am sorry to say.

What is wrong with it?

The major things one finds missing in so many “software documentations” are:

What am I looking at?

In the country where I was born – today it’s called Czechia – there used to be a TV programme where celebrities would guess the intended use of unfamiliar physical objects, often old domestic, kitchen, or garden tools.
The excitement of publishing a piece of software, the fatigue of doing so much programming, or the distaste towards writing English instead of a computer language, seems to prevent many software authors from describing what it actually is that they have made. It results in the potential users scratching their heads over what it is that they are looking at.

What is the context?

What is the motivation behind the creation

If you are investing time into writing it, you have a good reason for it, presumably. It fills a gap, it does something better, etc. Whatever it is, it needs to be described.

Which versions of software does it apply to?

Typically, one looks for libraries or components that would solve a problem at hand, would work in a given context and cooperate with a given version of a larger product. Some products use the same name but differ significantly across their versions (the Angular framework, for example). Google is great at making a match on key words, but it does not distinguish between different versions that well. One can end up studying a piece of software that is completely irrelevant. What a waste of time.

Blog posts

Then there are informative blog posts. They try to help but they can end up causing frustration and waste people’s time because the same deficiencies as above apply to them too. They sometimes don’t even include such a simple thing like the date when they were published, preventing one from making a simple call on their currency. Oh, come on!

Rubbish documentation sometimes leads to Chinese whispers and regurgitated content across many sites on the Internet. Trawling through all that can be really frustrating when one tries to figure something out.

Let’s improve the state of software documentation

The current state of software documentation has lead me to the, not so original, idea of software documentation testing. Before one publishes a piece of software or an informative blog post, one should get it reviewed by various people from different backgrounds.

It is not easy to step out of the box that one is currently in to write an article / piece of documentation that has everything that the intended audience needs to derive good value from it. But if we don’t do it, we end up contributing to tons of garbage that is out there already, quite possibly achieving the opposite of what we set out to do – to help others in some way, something that is very special and perhaps not that common in other fields.