Une nouvelle RFF, sur la documentation. Ça faisait un moment que j'avais envie d'écrire tout ça, même si certains trucs sont évidents ou connus en général.
The word "Documentation" designate many things. It is actually almost all except the source code. And even source code should contains doc (e.g. comments). There are two different types of doc : the one for people that use the program, and the one for people that contribute to it.
[Section 1] lists some general considerations about documentation. [Section 2] defines what sould be documented from a user point of you. [Section 3] do the same for devs.
Here are some general guidelines about documentation.
Writing documentation is not the most pleasant task when developping a program. It adds no feature, it takes time, it requires to organize ones ideas, etc.
So people use to say "Later" and report documentation to the time when there will be nothing to do but documentation. Unfortunately, this time does not exist.
The point is: However difficult to write down your ideas right now is, it will be far more difficult to do it later, when you will have forgotten half of your ideas or where they come from. You may actually don't understand what you tried to do before!
So when you add some feature, you MUST document it at the same time.
You can even document it before implementing it. It would help you see some problems and have the development easier since you will not have to stop at every line to think about fundamental implementation choices. Furthermore, it would help people contribute to your idea.
Although you have to write documentation, you also need to read it sometimes. That's what a documentation is made for actually! And so you SHOULD report issues in understanding it to the people that wrote it.
It may be because of you, but it usually means that there is a lack of something (at least a link to a required knowledge). So don't hesitate to say that something is not clear or baddly documented.
A documentation have some contradictory goals. It should be precise and be an answer to every question. But it should also be readable by people. And people are not machines so they need examples, they need to know where a technical choice come frome, etc.
The must is to have both a specification side, to which we can refere when we have a very precise question or when there is a conflict about some behaviour and on the other hand to provide some tutorial.
By "tutorial", I mean a text that aims to be didactic and drives the reader from one point of knowledge to another one, as linearly as possible. The reference, on the contrary, would more look like a tree that details everything but is hard to read page after page. It must not be designed to be read integrally but to make it easy to find precise information.
There are a lot of features, choices and ideas to document. This will automatically lead to very long articles (like this one).
This is important to be complete, especially for reference doc, but we can't considere that everybody will read everything. If there is no mean to quickly access information, nobody will be aware of choices.
Documentation need diversified entry points.
One of them have to be particularly well organised : the Getting started. This page should be synthetic and focus on what is really essential while giving information about how to read more about one topic or another. It must explain the fundamental ideas that drive the program and its development since this will help people understand why some things are where they are and guess whether a feature is included or has absolutely no reason to be there.
Another important entry point is a FAQ (Frequently Asked Questions) page that point to full documentation for further info (but for further info only, it must answer the questions).
Information must be easily accessible. Answering a question in the deepest comments of an old reported issue is no documentation. You should then add that explanation at the right place in the documentation to prevent people from asking it again.
Now that documentation has been defined in a general point of view, let's precise what kind of info should be documented for users and for contributors.
At first time, he have to install the program. Then he just wants to use the program for what he installed it. When people install Freeder, this is in order to read feeds. That's what the Getting Started should explain.
But people also want to discover features. There are two ways of discovering it:
Documentation not only refers to the text files lying beside the program but also designate the means provided by the user interface to understand the program and meet new functionalities.
In addition to the Getting Started and the FAQ, a list of key features with link to more info can be a very efficient way of informing users of what they can do.
It can be interesting to have a per feature wiki section with a common pattern of presentation:
The user spend of course more time using the program than reading its doc. What if the program itself would get him informed?
The first way to do so is to add tooltips everywhere the user could wonder what the interface element does. It should be implemented such as the user can easily ignore them since once he has read it, he does not need it anymore. But we cannot know whether he has read it or not, so it should always be there, in a corner of the interface.
We will think about other ways to drive the user wandering, but here are some ideas:
The contributor documentation should have its own Getting started and FAQ since contributors also need to get started and also have a lot of questions.
Contributors are more likely to read documentation, but they also lack time so we can't ask all of them to read the whole documentation before commiting the slightest feature.
There are different sections of development that need to communicate conventions. For example, themers need to know what info backend provides to them and backend devs must fill the requirements of themers.
Again, precise description of APIs is provided by the specification, but it may be useful to have examples of how to use it and what, among the list of all info, is really important to get started in a given field of development.
Beside the specification, the code itself should contain help. It can of course be in comments, and especially in doxygen-formatted ones since Freeder autogenerates dev documentation from its code. But it can also be implemented through tools like assertions.
Assertions shall never be raised in a common use of the program. But they intend to document theoretically never-happening situations for time when theory is overtaken by reality. It may happen in developpment side and it is a kind of documentation to have the program automatically say "Hey, your changes lead me to an absurde situation! You may have broken something…" instead of just crashing quietly.
Explain technical choices to avoid repeating why things are how they are.
There are a lot of decisions to make at any scale: it could be about using a table or a set of variables in that function in that file or about organizing the whole project.
Once we've done a choice, we need:
The points 2. and 3. does not need to be at the same place. People that want to know what the choices are not the same people that those who want to know why there have been taken. Or at least they don't want to know it at the same time.
For now, these explanations can be found in the Contributors wiki page.
Documentation is what enable people to help you. It is what remains when you stop maintaining the project. It is the only way to communicate with other contributors without being always aware of questions and wasting time repeating the same answers.
So don't neglect it.