[tracking] improving the onboarding experience

[maribu]

Description

RIOT does actually have a lot of good documentation, which however is difficult to find and poorly structure. Some documentation is outdated, lacking, or non-existend.

Let's try to fix this:

• Agree on what the "landing page" or "onboarding page" should be. (IMO the README.md in the Github repo.)
  • Re-evaluate and improve the documentation. Double check e.g. with students if they actually manage to get started with RIOT by themselves, given just the documentation
• Add missing doc
  • Setting up the toolchains (we had very outdated stuff on this in the Wiki)
  • Setting up common IDEs (unless they can automated)
  • Setting up the toolchains on Windows (this works quite well with WSL2 and USB-IP to do make flash and make term from within Linux to real hardware, it just needs to be better documented)
  • Link the board selection guide to the onboarding page
• Improve structure of navigation in the doc
  • Reorder the items in the navigation menu
  • Add more structure to the navigation menu (e.g. group all build system stuff, group "creating modules", "creating apps", "creating a driver", "creating a board", ...)
  • Clean up the documentation (e.g. KConfig is still prominent there, not reflection what is current consensus)
  • Fix the hot mess Doxygen does when there are target specific variants of types. (Maybe what we did with gpio_conf_t in GPIO LL could be a solution?)
  • Fix the CSS of the "Table of Contents" box (as seen in the upper right corner e.g. here https://doc.riot-os.org/flashing.html - looks fine on mobile, though)

[bergzand]

• Missing in the Contributing guidelines:
  • How to get a development environment set up
  • How to test a potential PR
  • In what way tests must be added

See also this FOSDEM talk on "Strategies for Building Healthy Open Source Communities"

[mguetschow]

• improve search
  • e.g., a search for "random" does not yield https://doc.riot-os.org/group__sys__random.html o.O
• clearly mark modules as such and provide their name
  • e.g. https://doc.riot-os.org/group__sys__random.html does not mention that you need to add USEMODULE += random to your Makefile
• unify board documentation
  • make sure to mention BOARD= identifier (see boards/feather-nrf52840*: doc cleanup #20422)
  • have same sections with same content for all boards

[miri64]

• Improve structure of navigation in the doc

There is an „Extreme WIP branch“ by @leandrolanzieri and @jia200x that ports our doxygen documentation to sphinx (using breathe): https://github.com/leandrolanzieri/RIOT/tree/pr/sphinx. Since Doxygen is a hot mess when it comes to modern styling, finishing this might be the better option than trying to fiddle around with the CSS.

[jkarinkl]

• Explain basic words and processes in a cheat sheet or glossary

  • Many words that are used are logical for you as experienced maintainers, but new to beginners.
  • For example this page about Git and GitHub explains quite some general things about Git already and they link to an even more detailed page which explains basic words and processes.
  • Example Glossary of Cloud Native here

• Add pictures and screenshots into explanatory documentation.

  • Not everyone prefers text (only) for learning new skills.

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

On tutorials:
(see https://forum.riot-os.org/t/riot-learning-solutions-request-for-input/4062/10 for more context)

• Place a link to the ‘regular’ tutorial 1 at the main RIOT page with information about how to get started (or a different page that will be the landing page for newcomers).

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

Since onboarding also has a lot to do with culture and a sense of belonging to the community, here are also suggestions for non-technical documentation.

• Explicitly describe tacit rules.

  • For example: "Asking questions is perfectly normal, please do so. You can use the chat and forum for this. In the beginning asking questions can be exciting, because you might not understand other questions asked. Remember that everyone started out with little knowledge about RIOT and that by asking your questions you are helping others who may have the same question!"
  • This explains two things, namely that it is common to ask questions and that we are aware that it can be difficult at first. By mentioning this explicitly, you lower the threshold for beginners to actually ask questions.
  • Here again: for experienced users/maintainers, asking questions makes sense, but beginners experience a (sometimes high) barrier here.

• Explain where and when new users can meet other users, e.g. forum/chat/hack 'n ack/summit

  • For newcomers to stick around, they need to feel like they belong to the community (besides the understanding of the software, of course)
  • Therefore, they need to know other community members and have contact with them
  • By mentioning the channels and events repeatedly at many documents/web pages, it becomes clear that these channels/events are main part of the community. Hence lowering the threshold to join in one of these events/channels.

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

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

[waehlisch]

Write an extensive example, work everything out in detail.

if this relates to code, the step-by-step code instructions should be part of test(s) that are part of every release.

[maribu]

Write an extensive example, work everything out in detail.

if this relates to code, the step-by-step code instructions should be part of test(s) that are part of every release.

This is an excellent point. Things easily bit-rot when not tested. I wonder if we should even add the tutorials into the main repo to keep them in sync and easier to find. The trade-off I see here is:

• 👎 main repo becoming more monolithic and possibly more overwhelming
• 👍 easier to find and link
• 👍 CI can enforce that the code still runs and even test on devices in nightly
• 👍 kept in sync with the code. (Specifically: When we break things due to API changes, should the tutorials be updated only when the new release comes out, or right away? What if users pick the master branch instead of the intended release branch because of a new feature? If the tutorials are in the code repo, they switching a branch will switch the tutorials as well.)

[jkarinkl]

Missing in the Contributing guidelines:

* [ ]  How to test a potential PR

This may be described as part of the 'Pull request checklist', see template below.

Adding on to the points mentioned in @bergzand's message:

See this template for a list of what should be included in Contributing Guidelines.

Also missing:

• Contribution ladder
  • Background info and template on contribution ladder
• A section on "come to meetings"
  • explaining which meetings we have (Hack'n Ack, Summit, more??) and inviting people to join.
• Pull request Lifecycle
  • description of what a contributor can expect during their pull request. This helps set expectations for both contributors and reviewers.
• Pull request checklist
• Prerequisites
  • Explicitly describe the steps needed before submitting code.
  • The code of conduct can be linked here as well, so that it does not need to be mentioned in every sub block of the contributing guidelines, as it is now.

[jkarinkl]

It would be good to label more PR's and issues as 'good first issue'. When searching on that label, I now only find 11 open issues, of which the most recent are from 2022.

Many documentation issues/PR's can be reviewed by a beginner as well, such as #20426.

[jkarinkl]

Write an extensive example, work everything out in detail.

if this relates to code, the step-by-step code instructions should be part of test(s) that are part of every release.

Yes, it relates to code and especially how to combine different parts of code.

If you want to build something that consists of different building blocks, it is currently difficult for a beginner to figure out how to combine these building blocks. Therefore, it would be nice if an example could be made of how to combine pieces of code, including references of where to get the different information from. This way, a beginner will learn how to find the necessary information together from the documentation.

[jkarinkl]

Write an extensive example, work everything out in detail.

if this relates to code, the step-by-step code instructions should be part of test(s) that are part of every release.

This is an excellent point. Things easily bit-rot when not tested. I wonder if we should even add the tutorials into the main repo to keep them in sync and easier to find. The trade-off I see here is:

* 👎 main repo becoming more monolithic and possibly more overwhelming

* 👍 easier to find and link

* 👍 CI can enforce that the code still runs and even test on devices in nightly

* 👍 kept in sync with the code. (Specifically: When we break things due to API changes, should the tutorials be updated only when the new release comes out, or right away? What if users pick the `master` branch instead of the intended release branch because of a new feature? If the tutorials are in the code repo, they switching a branch will switch the tutorials as well.)

I would like to see it in the main repo. It took me quite some searching work before I found it.

[miri64]

There could also be a „hybrid“ approach: include release-tests/Tutorials/... as a git sub-module.

[mguetschow]

• Improve structure of navigation in the doc

Here's a proposal from an intern here at TUD for the documentation structure:

• Getting Started
  • Roadmap
  • Creating modules
  • Creating an application
  • Porting boards
• Development Basics
  • Writing a Device Driver in RIOT
  • Flashing via RIOT's Build System
  • Build In Docker
  • Running and creating tests
  • Build System Basics
  • List of Features (Features as Build System Entities)
  • Kconfig in RIOT
• Advanced Development Techniques
  • Using C++ in RIOT
  • Using Rust in RIOT
  • Advanced build system tricks
  • Debugging
  • Tools
• Emulators, Release and Maintenance
  • Release cycle
  • Changelog
  • Removed Features and Modules
  • Deprecated List
  • Todo List
• Hardware and Configuration
  • Supported Boards
  • IO-Mapping and Shields
• Documentation and Organization
  • Topics
  • Namespaces
  • Data Structures
  • Files

[maribu]

• Improve the example apps
  • Add some structure
    • group CoAP, MQTT, and MQTT-SN into a network folder
    • add a machine learning folder and examples of the different packages and tools we have
    • add a board folder that shows off features of a limited number of boards, e.g. a few picks from the recommended board page (maybe the Adafruit Feather Sense due to its use for teaching) and a number of boards of different categories, e.g. "board with display"