Documentation breakout session 2023

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: image

(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.

What about the riot-course? It was developed especially for newcomers.

Thank you for your input!

One of the ideas behind the tutorials that might not be very clear above is that they can be used in an individual setting by newcomers and beginner-level RIOTees. With individual setting I mean that they can try it from home or as part of a self study exercise from either an academic and/or industry setting.

In my opinion the riot-course is an excellent set of slides and materials for an interactive tutorial during the summit and other events. However I think the way it is set up is not really suitable for learning in an individual setting. I do think the material, as in learning goals and overall material, can be reused in the tutorials I proposed above.

Altogether I think that the material in the riot-course and in the tutorial will overlap a lot, but that the setting in which it is used is pretty much orthogonal.

What do you think?

I have a background in teaching and designing education, happy to help out on that one.


That would be be awesome. There is NOTHING worse than following a tutorial which is broken because something changed. HOWEVER, it’s not CI code, and it needs to avoid trying to exercise all the options.

This reminds me of: Situational leadership theory - Wikipedia Hersey-Blanchard Model - Definition, How it Works has a good picture. Note how there are four quadrants, and new people start in “Telling”, and move upwards to “Selling”, and then “Participating” and finally “Delegating”. Our problem is that most of us are in the Delegating category: we can just eff-off and do our thing, and we expect others to be able to do the same. New people need telling in the form of tutorials. Then, they need Selling (“How-To Guides”). Then Explanation and then Reference. (So our diagram is not in the same order as Hersey-Blanchard)

Because we are used to being Participants, it’s often hard for us to understand the needs of people in the other quadrants.

1 Like