Description

The maintainer guidelines and RDM0 give some indication of the contents and review criteria for documentation. Do we need a bespoke set of across-the-board documentation standards? This could:

• give the same style ("look and feel") to all documentation
• encourage documentation to be more complete, which would allow readers to read and understand without having to ask questions
• make it easier and quicker to review documentation

Some items that could be specified could be:

• Examples of a few different types of documents and what their scope, contents and target audience should be
• Details of process when documents relate to code (design documents finalised before PR submission? Documents can have expected revisions? etc)
• Hard requirements on completeness before merging, particularly for API documentation
• RIOT-specific terminology (What is a "module"? etc)
• Requirements on spelling, punctuation and grammar

Here's an example from Django.

Related issues:

#8479
#7889