One of the things I most often find missing from the documentation for a program or library is anything telling me why I would ever want to use it. In extreme cases, it can be hard to find any formal documentation telling you what the program or library is or does. This “Why-To” documentation as I like to call it is vital, but so often not there.
If you’ve ever had to track back through package dependencies, you’ve probably come across a package with a memorable but unhelpful name like libgruffalo. You may even have been able to find API documentation that shows you functions to fox, snake, owl or mouse, with a note that the mouse functionality is experimental and may cause libgruffalo to segfault. What you will not find is any indication of what libgruffalo does, or what foxing, snaking or owling might entail. You’ve probably just shrugged your shoulders at that, and hoped that you never have to debug any problems that arise from it.
I’ve always thought of software like this as supremely useless. There is no point in releasing libgruffalo out into the world in that state, because no one who needs it is ever going to find it. You should at the very least have some documentation telling potential users what libgruffalo is and does, and why a programmer might want to use it rather than write their own implementation. It doesn’t even have to be long, but it should be the very first thing someone hunting on the internet comes across about your code. READMEs are a good place for this sort of thing. All too often they contain detailed instructions for installing the software on every platform imaginable, but nothing saying why you might want to do such a thing.
I was going to offer Redis as an example of how to do this properly. We’ve used it very successfully in the past and I remember the website being quite clear, the documentation pages well structured and it generally being pretty easy to find out anything I wanted to know. There were even a couple of concepts that could have been explained better that I could have complained about just for balance. That documentation is still there, but the current website design makes it a good deal harder to find. The home page has had the sort of makeover that uses the word “AI” as often as possible, and I couldn’t actually find anything mentioning what their software does at all. (It’s an excellent in-memory database, in case you didn’t know.)
Now in the case of Redis, it’s probably true that most people who need their software already know about it, so it’s not a big deal that it isn’t the very first thing you see on their site. For others, particularly if the product’s name isn’t incredibly obvious, you really need that up-front statement of what it is and why everyone should want it. For example the Python package “spotless” could be practically anything given just its name. Its project page on PyPI immediately tells you that it is a “Radio Interferometry Imaging Algorithm”, followed by more information that presumably means something to people interested in radio interferometry. It seems obvious to me that anything you put out in the world for other people to use should have a few paragraphs like that — heck, just a sentence can be enough — to indicate its purpose. I’m constantly surprised that so many don’t.
The one thing someone browsing the internet should be able to trivially find out about your project is what it does. Otherwise they will never care about it.