[Tracking Issue] Documentation Improvements

[emmanuelsearch]

Some pieces need to be improved/updated, while others are missing still. Let's track that here. (You spot more items? You think of a better substructure? You're welcome to modify/update or discuss it here!)

TODO short-term

• Update main README README: updated text #154

• Add code of conduct Add Code of Conduct #163

• Add a roadmap Roadmap #242

• Add comparison with competition Documentation: Add comparison with other platforms #345

• Document Wifi use on Rpico Document RasPi Pico including Wifi use #342

• Add a new contributor guide RIOT-rs Contributing Guide #151

• Add an initial porting guide (some info in this pad) Add a porting guide #343

• Add board feature support matrix somewhere docs(book): add an initial version of the support matrix #324

• Documentation: document current governance #344

• Remove outdated documentation

• Guidelines on which log level to use when

• Initial mdbook drafting

  • Add initial manifesto Book: added manifesto #131
  • Draft Intro / Overview Book: intro architecture diagram and text #153
  • Add doc on the scheduler book: add sections about threading #152
  • Draft overall concept to (sub)structure the book
  • Book content updates automation (?)

TODO mid- & long-term

• tutorial: provide one
• Document / track formal verification Tracking formal verification status #140

[jkarinkl]

Good to have an overview on documentation to do's. Suggested additions:

• Add a roadmap (see background information)
• Add a glossary, explaining basic words and processes (see example)
• Make a tutorial (not sure at what point in time this should be made. Is it too early?)

It would also be great to have a GOVERNANCE.md document in time. This helps clarify who has what role and how decisions are made. However, it is recommended to formalize this when a project is a bit further along, as it gradually becomes clear which form suits the project.

• See background information from Open Source Guides and Cloud Native.
• An example from Grafana is found here.

It would be good to keep this in mind on what is desired on governance for the project, so that we can put it into a document easily in time.

[emmanuelsearch]

thanks @jkarinkl We're already in a position where we have a roadmap, so I'm adding this to the TODOs (see above).

Concerning a glossary, maybe we'll need one at some point, but maybe we don't need one just yet (let's wait until some non-well-defined terms actually emerge as such?)

A tutorial would be great indeed, but it's a tad too soon in my opinion too.
We also need to think about governance indeed in the near future.
I went ahead and split the TODOs in short- vs long-term items at first sight.