Documentation 101
Over the time the RIOT community has developed several ways to document RIOT's features
- the on-line API documentation that is generated from the Doxygen comments in the source code,
- several READMEs in the source code repository (e.g. the README for native and of several applications), and
- the Github-Wiki.
We assessed that every one of these is useful on its own for different use-cases:
- The doxygen documentation is close to the code and changes in the code result for the most part in changes to the API documentation, too.
- README files also are directly connected to their relevant modules or applications.
- The Wiki is accessible for everyone in the RIOT community and is in most cases the first place people look for answers.
Based on this observations we formulated some rules that should give you some direction where to put your documentation.
The doxygen documentation is primarily used to document behavior, usage and interfaces directly related to the code. If you write a new module describe your ideas for that module, how it works and how you can use its functionalities in the detailed description of your module or its functions. You can even provide small inline code examples for their usage.
READMEs shall be used primarily to describe the usage of applications or a tool but they might also useful in other cases:
- to give a non-functional overview over the contents of a directory (a README.md in a directory will always be picked and parsed by GitHub in the tree view of the directory).
- to describe some special behavior (new build targets, special macros etc) of the build system for a specific platform
The Wiki shall be used primarily for How-Tos and hardware documentation. It also shall provide links to Doxygen pages and READMEs of special interest at a point that is easy to be found for everyone.