These are my notes based on what I remember from todays breakout session on documentation at the RIOT summit.
@oleg started with a number of shortcomings in our documentation. Main issue was that supported functionality is hard to find.
After this we discussed the four approaches to documentation for a while:
(During the breakout session I only vaguely remembered the quadrants, but here is the actual thing. I was under the assumption that ‘Explanation’ was a Q&A quadrant and covered by the forum, but it is different.)
We identified that we cover the ‘Reference’ aspect with the API documentation, but that we do not have the ‘How-to’ covered and also the ‘Tutorial’ quadrant is barely covered by what we have today. In general there was consensus that the current state of the tutorials is not sufficient to cater to needs of newcomers.
We also identified that a number of examples in the tree currently have a readme file that contains a mixture of tutorial-type documentation and reference info for the example. One example mentioned was the gnrc border router.
One proposal by me was to revive the idea of mine to write an mdbook with step-by-step tutorials (also this pad). During the discussion it became clear that this should live in the RIOT tree so that code snippets could be drawn from fully completed tutorial examples and where the CI would include these tutorial examples in the builds. This way it becomes clear for maintainers that the tutorial text itself should at least be checked for validity when the example is modified, e.g. due to an API change.
Tutorials themselves would have a consistent format, explained in tutorial 0: writing tutorials, with clearly defined learning goals and a incremental format between sequences of tutorial. A sequence of tutorials could have a final goal of setting up a few gcoap endpoints on a RIOT device, with intermediate tutorials to set up networking. A single tutorial should take preferably between 20 minutes and an hour or so, to make them short enough for an afternoon project or achieve a larger sequence after a weekend of programming.
The conclusion on this is that we slowly want to move to such a structure, preferably recycling existing tutorials into this format.
The other aspect we briefly touched was the Doxygen documentation and the inconsistent module documentation in there. While all modules have the functions, macros and other code bits documented as enforced by the CI, the level of usage documentation varies a lot between modules. Some modules have a single line description of the module, others have multiple paragraphs of usage info. The proposal here was also to (again) create a template for the module descriptions. Current documentation can be slowly converted and new documentation can be created according to this template.
Let me know if I’ve missed something here.