Module Docs Guidelines#
This page provides guidelines on how to write documentation for a single Pigweed module.
These guidelines are a work-in-progress. Most of the guidelines are recommendations, not requirements, because we’re still figuring out which guidelines are truly universal to all modules and which ones only work for certain types of modules.
Choose your adventure#
Our guidance for you changes depending on the nature of the module you’re documenting. This flowchart summarizes the decision path:
Simple modules versus complex modules#
We’re currently focused on updating the docs for “simple” modules. Here’s our general definition for a simple module:
The module’s API is end-user-facing or HAL-facing, not infrastructure-facing.
The module does not use facades.
The module’s API surface is small or medium in size.
The module’s API is in a single programming language.
If your module doesn’t meet these criteria, it’s probably a “complex” module. Create an issue before attempting to refactor a complex module’s docs.
Why the focus on simple modules? We tried refactoring complex modules to adhere to SEED-0102. The migrations were difficult and the resulting docs weren’t an obvious improvement. We learned that it’s more effective to focus on simple modules for now and take more time to figure out what works for complex modules.
Examples of simple modules:
Examples of complex modules:
Simple module guidelines#
Follow these guidelines if you’re writing docs for a simple module.
Single-page approach versus multi-page approach#
If your module meets the following criteria then you should probably use the Single-page approach:
There is less than 1000 words of content in total.
The API has 2 classes or less.
The API has 10 methods or less.
If your module doesn’t meet all these criteria, then you should probably use the Multi-page approach. As you can tell by our use of probably, this is just a soft guideline. E.g. if you have 2000 words of content but you feel strongly that the single-page approach is better for your module, then go for it!
The content that you write mostly stays the same whether you use the single-page or multi-page approach. All modules must have Sales pitch content for example. The only difference is that in the single-page approach this is the first section of content whereas in the multi-page approach it’s the first page of content.
When using the single-page approach, this is the default ordering of
The sales pitch must come first, followed by the getting started instructions. Everything else beyond that is optional. The sections can be re-arranged if you feel strongly about it, but we’ve found this is an intuitive ordering.
The file must be located at
replaced with the actual name of your module.
When using the multi-page approach, this is the default ordering of pages:
The Sales pitch content.
The API reference content.
The Design content. See the note below.
The Size analysis content.
The sales pitch and getting started instructions are required. Everything else is optional. The sections can be re-arranged if you feel strongly about it, but we’ve found that this is an intuitive ordering.
You can split
Get Started & Guides into 2 docs if that works better for
your module. The filenames should be
Design & Roadmap can also be split into 2 docs. The filenames should be
The following sections provide instructions on how to write each content type.
We call them “content types” because in the
Single-page approach each of these things represent a
section of content on
docs.rst whereas in the
Multi-page approach they might be an entire page of
content or a section within a page.
The sales pitch should:
Assume that the reader is an embedded developer.
Clearly explain how the reader’s work as an embedded developer will improve if they adopt the module.
Provide a code sample demonstrating one of the most important problems the module solves. (Only required for modules that expose an API.)
The get started instructions should:
Show how to get set up in Bazel, GN, and CMake.
Present Bazel instructions first.
Clearly state when a build system isn’t supported.
Format the instructions with the
.. tab-set::directive. See
//pw_string/guide.rstfor an example. The Bazel instructions are presented in the first tab, the GN instructions in the next, and so on.
Demonstrate how to complete a common use case. See the next paragraph.
If your get started content is on the same page as your guides, then the get started section doesn’t need to demonstrate a common use case. The reader can just scroll down and see how to complete common tasks. If your get started content is a standalone page, it should demonstrate how to complete a common task. The reader shouldn’t have to dig around multiple docs just to figure out how to do something useful with the module.
Get Started (pw_string)
The guides should:
Focus on how to solve real-world problems with the module. See About how-to guides.
The API reference should:
Be auto-generated from Doxygen documentation style (for C++ / C APIs) or autodoc (for Python APIs).
Provide a code example demonstrating how to use the class, at minimum. Consider whether it’s also helpful to provide more granular examples demonstrating how to use each method, variable, etc.
The typical approach is to order everything alphabetically. Some module docs group classes logically according to the tasks they’re related to. We don’t have a hard guideline here because we’re not sure one of these approaches is universally better than the other.
The design content should:
Design of pw::InlineString (pw_string)
The roadmap should:
Focus on things known to be missing today that could make sense in the future. The reader should be encouraged to talk to the Pigweed team.
The roadmap should not:
Make very definite guarantees that a particular feature will ship by a certain date. You can get an exception if you really need to do this, but it should be avoided in most cases.
The size analysis should:
Be auto-generated. See the
We elevate the size analysis to its own section or page because it’s a very important consideration for many embedded developers.
Code Size Analysis (pw_string)