During the Summit breakout session about documentation (19 September 2023), it became clear that new RIOT-OS users experience difficulties in how to get started. It was suggested to design a ‘tutorial 0’ (format for writing tutorials) and templates for module descriptions. Laura Mellendijk and I have a background in Learning and Development and we’d like to help in resolving difficulties in this area. We would like to first get a clear view of the current situation and desired future situation, so we can help to bridge the gap between both.
What we’ve discovered so far:
The API (doc.riot-os.org) contains reference documentation describing the available modules of RIOT.
Let me answer your easy questions about “besides new users”.
I’m a rather seasoned (30+ years) embedded systems expert.
I have problems knowing how things in RIOT-OS have changed: specifically, I probably am ignorant of features and facilities in RIOT-OS which probably make my life easier, but they weren’t there two years ago, so I improvised. Tutorials need to exist at multiple (“fractal”) levels of complexity so that new people are not overwhelmed, but also so that seasoned people read them and comment on how things are better/worse, and how they can help new people.
My experience observing and trying to help on the forum is that many new people, being inexperienced, often come with entirely unrealistic notions about how to do things, and the kind of background required. Let me make an analogy:
A new jumper arrives at the Olympic Ski Jumping slope. They plan to do a triple-axel 720 degree flip.
They start discussing the required momentum changes that they will need in order to accomplish that with the first person they see, who happens to be a snow maintenance person. “Wow, that’s gonna be something to see. What colour skis are you gonna wear? It would be cool if they were flurorescent!”
New jumper: “Wait, this sport is done on skis”?
So a key part of any tutorial would be to identify what skills are required for each step, and then to point the new developer to the non-RIOT-OS specific training materials that provide the background.
I recently came across this website, that might be helpful in structuring RIOT’s documentation : https://documentation.divio.com/.
As a new user, I can tell I’m having a hard time. But I hang on : I read examples and tests in the repo, often after reading posts in this forum, that point to the most relevant ones. But what strikes me most, is that the so-called “detailed description” in the documentation is too often no longer than a single line. That sure doesn’t help figure out realistic use cases…
I think the challenge is definitely worth the effort, since the learning curve is a major criteria in selecting a RTOS. And it implies effective documentation.
thanks for picking up our discussion from the Summit.
I try to provide some input from two perspectives:
1.) My own perspective as someone who used to know almost everything about RIOT
but whose knowledge has outdated over the years quite a bit.
2.) The perspective of my students who are mostly completely new to RIOT (and
often to embedded programming at all).
The API (doc.riot-os.org) contains reference documentation describing the available modules of RIOT.
You’re right: initially this location by a has been meant for providing the
API documentation. However, over the time we decided to make it the default
location for most/all documentation.
(By the way, in case you’re not aware): This part of the documentation is
automatically generated from code and text files inside the RIOT source code
repository by a tool called doxygen. Hence, I will refer to it as “doxygen
documentation” in the following.)
When students ask me who do perform a particular feature in RIOT (or in
working with RIOT) I often know that this feature exists but cannot recall
exactly what needs to be done to use. In these cases, I often experience some
difficulties in finding the documentation.
The main reason for these difficulties is a) not everything is (yet)
documented in the doxygen documentation, b) the structure of the
documentation is not coherent, the search function is of limited use
(particular if you do not exactly what to search for).
For example:
For our native “board”, the required packages are documented directly on the
entry page: Native Board
For other boards, you need to look at the getting started page:
Getting started
I typically give a pointer to this tutorial for RIOT newcomers. But since this
tutorial has originally been designed as a guided tutorial some things
are often difficult to figure out when the students are on their own. (E.g.,
which packages need to be installed when working on their own Linux
installation.)
New users ask many questions in the chat and forum about how to get
started using RIOT to build their specific project.
Many people seem to hesitate from asking beginners’ questions in the forum or
on Matrix - even though people are usually quite helpful and friendly. Maybe
we need a particular newbie section in the forum and/or a newbie channel in
Matrix.
For whom, besides new users, is this a problem?
I can only second what Michael wrote. It is often difficult to keep track of
changes for experienced users who are not following the development that
closely. Maybe we could think about periodic newsletter or blog which offers
some sort of documented changelog.
Cheers
Oleg
–
/*
For moronic filesystems that do not allow holes in file.
We may have to extend the file.
*/
linux-2.4.0-test2/fs/buffer.c
While there were thoughts about merging this, I think at this point I am against these: Every tutorial was designed with a different goal, a different target audience in mind, and that is a good thing. Especially with learning material, I came to the conclusion that there is no one-fits-all solution (some like to dig through the API doc from the start, others like to go through a step-by-step tutorial, yet others again like to look at examples and even in these groups people approach things differently).
However, maybe it would be a good idea to put some of the newer stuff from riot-exercises and riot-course that worked well also into Tutorials?
Thank you very much for your reactions! They are very helpful in giving us a better overview of the current situation. Also thanks for suggesting so many possible solutions, this is very valuable.
A short summary so far:
Beginners seem to have a hard time getting into RIOT (but they hang on! Very nice, @emeutier ) . They lack some basic knowledge, documentation is incomplete and/or it is unclear where to find what. Also there is no easy ‘entrance’ to start using modules based on the API. The online tutorial seems to be outdated and is difficult to use on your own. Forum posts, however, help beginners in finding the most relevant examples and tests in the repository.
In general, documentation is seen as a concern. It is hard to get it logical, retrievable and complete.
Other area for improvement is keeping up with added features to the code for experienced users, which could be solved by a periodic newsletter/blog or a timeline with features added. Would this be possible to add to every release (@maintainers)?
Since there are diverse areas for improvement, we decided to first focus on facilitating getting started with RIOT for beginners. Therefore, we would like to know as well:
What does already work well for new users?
Can you describe what the most ideal start for beginners with RIOT would look like?
We would like to also talk individually with some new RIOT users to get more in-depth information about their experiences. If you are a beginner with RIOT and open to this, please let us know! (in reaction to this post or via Matrix @karinkl:utwente.io)
Hello all, here a short update on the learning solutions for RIOT newcomers.
We have had our first conversations with individual community members, which have given us many interesting insights. More interviews will follow in the next weeks, after which I will provide a more substantive update here.
If you would like to share your experience or other information relevant to improving the learning process of beginners, please send me a message via forum or chat!
After speaking with 5 people from the community about learning solutions for RIOT newcomers, I have found out the following about learning solutions for RIOT newcomers.
There are three different tutorials/courses available:
Intended as the leading tutorial during summit (before corona).
This uses Jupiter Notebook, via browser, no hardware needed.
License CC-BY-ND, so it cannot be adapted and redistributed.
Nice start for who wants to use RIOT for research work
Tutorial and exercises for students of HAW and TU Dresden
This has first been made for the RIOT summit +/- 2017.
This material is used for teaching at HAW for some years now, TU Dresden will start using it this semester. Both links lead to the same content; a different link is used to prevent confusion for students of both universities.
Hardware is used in these tutorials, so students learn to use RIOT on hardware.
My findings on preferred ways of learning RIOT:
Beginners differ in preferred way of learning. Experienced (and mostly 30+) users prefer written explanations and documentation. Younger users (students) often prefer a combination of written and video explanation.
Most people prefer to first get an overall introduction from someone, before doing a tutorial by yourself. Also because tutorials 1 ‘regular’ tutorial and 3 HAW/TU Dresden tutorial are not intended and suitable to be completed entirely on your own (not sure how this is with the 2 RIOT course).
Everyone likes it when there is a real person available to explain and ask questions to. This may be online or offline. For online asking for help, it is preferable that the beginner knows the person (s)he asks questions. Otherwise the threshold for asking help is high, because of fear of asking dumb questions.
Recommended improvements, mentioned by the interviewees and myself
Indicate at the start of the tutorial what skills are required to successfully finish the tutorial. For example: makefile, build system, git, Jupiter. This allows the person who wants to do the tutorial to easily see if they meet the requirements.
Make an overview with links to the non-RIOT specific training materials needed to start with the RIOT tutorial (for example: makefile, build system, git). Place this link at the start of the tutorial, with the ‘skills required to successfully finish the tutorial’. This allows the person who wants to do the tutorial to brush up their lacking knowledge themselves so that they will be able to successfully complete the RIOT tutorial.
Improve the ‘regular’ tutorial 1 with good parts of the RIOT course 2 and Tutorial and exercises for students of HAW/TU Dresden 3. This is a big(ger) task, checking out the material of all three tutorials and decide on what content could be added where.
Create more elaborate examples
Write an extensive example, work everything out in detail. For example for use model. So that you instruct people with such example where to find the information, so that they can find such information themselves.
Mark solutions on questions in the forum the same way as stack overflow, just as has been done with this post. This makes it easier for beginners to find solutions to questions that have already been asked on the forum.
Encourage beginners to ask questions
Encourage beginners to ask questions in more places. Have mentioned in all beginners documentation that you may absolutely ask questions and where they can do so (forum, chat). Put this in the tutorial, in the ‘getting started guide’ etc. So that it is everywhere and a beginner hopefully feels a lower threshold in asking questions. “Have doubts? Ask us!”
Create a matrix chat for RIOT newcomers. This may lower the threshold to ask questions, because it is intended especially for beginners. Explicitly show that we care about newcomers.
A lot of other important topics with suggestions for improvement came up during the conversations. Documentation has been discussed extensively, on-boarding in general, communication tools, good practices of other projects and the RIOT community. I would like to share the more about these topics as well. In which topics does the greatest need lie/would you like to receive more information? And where is the best place to share this information?
Final remarks
I think we can make a lot of great improvements for the on-boarding of beginners and would be happy to help further on this in the coming time. So please let me know if you’re also working on bits of on-boarding and other community-related stuff, because I like to connect and think & help along! Together we can implement a lot of small areas for improvement piece by piece, making the start and on-boarding for newcomers easier and the community as a whole even greater!
) . They lack some basic knowledge, documentation is incomplete and/or it is unclear where to find what. Also there is no easy ‘entrance’ to start using modules based on the API. The online tutorial seems to be outdated and is difficult to use on your own. Forum posts, however, help beginners in finding the most relevant examples and tests in the repository.