Open maribu opened 6 months ago
See also this FOSDEM talk on "Strategies for Building Healthy Open Source Communities"
USEMODULE += random
to your Makefile
BOARD=
identifier (see #20422)
- [ ] 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.
[ ] Explain basic words and processes in a cheat sheet or glossary
[ ] Add pictures and screenshots into explanatory documentation.
[ ] Write an extensive example, work everything out in detail.
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.
[ ] Make an overview with links to the non-RIOT specific training materials needed to start with 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.
[ ] Explain where and when new users can meet other users, e.g. forum/chat/hack 'n ack/summit
[ ] Create a matrix chat for RIOT newcomers.
[ ] Mark solutions on questions in the forum the same way as stack overflow
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.
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:
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.)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:
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.
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.
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.
There could also be a „hybrid“ approach: include release-tests/Tutorials/... as a git sub-module.
- [ ] Improve structure of navigation in the doc
Here's a proposal from an intern here at TUD for the documentation structure:
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:
make flash
andmake term
from within Linux to real hardware, it just needs to be better documented)gpio_conf_t
in GPIO LL could be a solution?)