Documentation at the right place

When programming a piece of software, whether it is an application, a library, a set of scripts, it is always important to add some documentation to the project, specially if it is a self-hosted tool (with an API), or a library that makes some tasks easier for other programmers. A good documentation not only helps future programmers with your software, but it also helps by solving questions people can have, thus freeing you to reply them in your support channels.

But sometimes programmers do not put the documentation at the right place. An example would be an Android library called sandwich. I stumbled upon it the other day, and when I started to look into the project, I saw the README. The documentation for the whole library is at the README.

A README for a project should contain:

• A short description indicating the scope of the project.
• Links to the documentation of the project, not only the API (if it exists) but also how to install/deploy it and a basic initial setup. An advanced documentation should be provided as well if needed.
• Links to the documentation about how to contribute to the project (not only with code but also reporting issues).
• Links to the support channels.
• (Optional) Links to the social networks you use to announce updates for the project.

If you are hosting your code at some Git hosting, it is possible that platform already provides you with a way to create man pages or a wiki, or any other place where the documentation should live.

SourceHut provides man.sr.ht, a git-based wiki that can be attached to a project. Any GitHub-like hosting, such as Gitea or GitLab also provides an integrated wiki within the project that can also be managed using git.

If you do not want to use those methods, you can always add a man or doc folder inside the repository itself with the documentation for your project.

The documentation should also be organized and linkable for any part of the documentation itself, so table of contents and references to other parts of the documentation can be made easily and without almost no effort. That would be very convinient for the users using your software.

A couple of examples of this:

• soju, an IRC bouncer.
• ACRA, an Android library for reporting crashes.

Next time you make a project, or if you already have some projects, take some time to review the documentation and see if you can improve it by using the tools we have for this purpose. It will be a huge boost for your project, and maybe even a point of reference for other people.