0102: Consistent Module Documentation#

Pigweed AI summary: This paragraph summarizes the proposal for consistent module documentation in Pigweed. The proposal suggests a structure for module documentation that includes three fundamental documents: "docs.rst" which provides basic information about the module, "design.rst" and "concepts.rst" which explain the design and background of the module, and "guides.rst" which provides instructions on how to use the module. Additionally, there are optional documents for interface documentation, such as "api.rst" for the external API

SEED-0102: Consistent Module Documentation

Status: Open for Comments Last Call Accepted Rejected

Proposal Date: 2023-02-10

CL: pwrev/128811, pwrev/130410

Summary#

Pigweed AI summary: This proposal suggests that Pigweed modules should have comprehensive and consistent documentation to help users determine if using the module is the right choice for them. The proposal includes a documentation philosophy and a flexible yet consistent structure for all module docs to follow. The focus is on improving the documentation experience for users, with "users" defined as developers using Pigweed in downstream projects.

Pigweed modules ought to have documentation that is reasonably comprehensive, that has a consistent and predictable format, and that provides the reader with sufficient information to judge whether using the module is the right choice for them. This SEED proposes a documentation philosophy applicable to all Pigweed modules and a flexible yet consistent structure to which all module docs should conform.

Definitions#

Pigweed AI summary: This section defines the terms "users" and "maintainers" in the context of Pigweed development. Users are defined as developers using Pigweed in downstream projects, while maintainers are developers working on upstream Pigweed. The main goal of this SEED is to enhance the documentation experience for users.

In this SEED, we define users as developers using Pigweed in downstream projects, and maintainers as developers working on upstream Pigweed. The primary focus of this SEED is to improve the documentation experience for users.

Motivation#

Pigweed AI summary: Pigweed modules require a minimum of a single documentation file, which provides no guidance or structure for maintainers to write effective documentation. This SEED proposes a framework for technical documentation that ensures modules have coverage across four quadrants: tutorials, guides, concept and design docs, and interface reference. The focus is on improving module documentation, which has the largest impact with the least amount of investment and can be used to construct higher-level and cross-cutting documentation. While not the only important documentation, module

Currently, each Pigweed module is required to have, at minimum, a single docs.rst file that contains the module’s documentation. This gives the module maintainer considerable discretion to provide as much or as little documentation as they would like. However, this approach fails for Pigweed maintainers by providing no guidance or structure to help them write effective documentation, and certainly fails Pigweed users who struggle to find the information they’re looking for. So a solution needs to make it easier for Pigweed maintainers to write good documentation, thereby making Pigweed much more accessible to its users.

Pigweed’s design is inherently and intentionally modular. So documentation at the level of the module is the most natural place to make impactful improvements, while avoiding a fundamental restructuring of the Pigweed documentation. Module docs are also what the majority of Pigweed users rely on most. As a result, this SEED is focused exclusively on improving module documentation.

Diátaxis proposes a four-mode framework for technical documentation, illustrated below with terminology altered to better match Pigweed’s needs:

	Serve our study	Serve our work
Practical steps	Tutorials (learning-oriented)	Guides (task-oriented)
Theoretical knowledge	Concept & design docs (understanding-oriented)	Interface reference (information-oriented)

Pigweed needs a framework that ensures modules have coverage across these four quadrants. That framework should provide a structure that makes it easier for maintainers to write effective documentation, and a single page that provides the most basic information a user needs to understand the module.

Alternatives#

Pigweed AI summary: The focus on module documentation comes with risks, as it may produce feature-focused docs instead of task-focused ones, and reduce the attention given to content that integrates across multiple modules. However, this approach is justified as it has the largest impact with the least amount of investment, and it is easier to construct higher-level and cross-cutting documentation from well-developed module docs. Additionally, module owners are natural candidates to maintain their modules' docs. Nonetheless, higher level introductory and guidance material that integrates Pigweed

There are risks to focusing on module docs:

The most useful docs are those that focus on tasks rather than system features. The module-focused approach risks producing feature-focused docs rather than task-focused docs, since the tasks users need to complete may not fit within the boundaries of a module.
Likewise, focusing on module documentation reduces focus on content that integrates across multiple modules.

The justification for focusing on module documentation doesn’t imply that module docs are the only docs that matter. Higher level introductory and guidance material that integrates Pigweed as a system and covers cross cutting concerns is also important, and would arguably be more effective at bringing new developers into the Pigweed ecosystem. However, this SEED proposes focusing on module docs for two primary reasons:

Improving module docs and providing them with a consistent structure will have the largest impact with the least amount of investment.
It will be easier to construct higher-level and cross-cutting documentation from well-developed module docs compared to going the other direction.

While not a primary consideration, a bonus of a module-focused approach is that modules already have owners, and those owners are natural candidates to be the maintainers of their modules’ docs.

Proposal#

Pigweed AI summary: The proposal suggests a standardized structure for Pigweed module directories, including required documents such as docs.rst, design.rst, and guides.rst. The proposal also outlines optional documents such as api.rst, cli.rst, and tutorials. The structure is flexible and can be adapted to meet the needs of individual modules. A template for implementing this structure is provided.

This change would require each module directory to match this structure:

module root directory/
├── docs.rst
├── concepts.rst [or concepts/...] [when needed]
├── design.rst [or design/...] [when needed]
├── guides.rst [or guides/...] [when needed]
│
├── tutorials/ [aspirational]
│   ├── index.rst
│   └── ...
│
├── api.rst [or api/...] [if applicable]
├── cli.rst [if applicable]
└── gui.rst [if applicable]

Fundamental module docs#

Pigweed AI summary: The "Fundamental module docs" consist of three required documents for every Pigweed module: "docs.rst" for basic information about the module, "design.rst" and "concepts.rst" for background on the module's design goals and implementation details, and "guides.rst" for specific outcomes and integration into a project. These documents can be organized into subdirectories if they become too large.

These three documents are the minimum required of every Pigweed module.

The basics: `docs.rst`#

Pigweed AI summary: This section provides basic information about a module, including its purpose and the problems it aims to solve. It also includes details that can help users quickly determine if the module is useful for them.

Basic, structured information about the module, including what it does, what problems it’s designed solve, and information that lets a user quickly evaluate if the module is useful to them.

How it works and why: `design.rst` & `concepts.rst` (understanding-oriented)#

Pigweed AI summary: This paragraph discusses the importance of documenting the design goals, assumptions, limitations, and implementation details of a module, as well as contrasting the design with alternative solutions. This information can be included in the "Design considerations" section of the index and can grow into a separate document as the module matures. Additionally, some modules may require documentation on fundamental concepts that are independent of the module's solution, which can be included in a separate "concepts.rst" file or subdirectory.

Background on the design goals, assumptions, limitations, and implementation details of a module, and may contrast the design of the module with alternative solutions.

This content can start in the “Design considerations” section of the index, and grow into this separate document as the module matures. If that document becomes too large, the single design.rst file can be replaced by a design subdirectory containing more than one nested doc.

Some modules may need documentation on fundamental concepts that are independent of the module’s solution. For example, a module that provides a reliable transport layer may include a conceptual description of reliable transport in general in a concepts.rst file or concepts subdirectory.

How to get stuff done: `guides.rst` (task-oriented)#

Pigweed AI summary: This section provides guidelines for creating task-oriented guides that focus on specific outcomes and should be created when a question is answered multiple times. Each module should have at least one guide on integrating it into a project and one guide on the most common use case. The content can start in the "Getting started" section and grow into a separate document as the module matures. If the document becomes too large, it can be replaced with a subdirectory containing multiple guides.

These are focused on specific outcomes and should be produced as soon as we see a question being answered multiple times. Each module should have at least one guide on integrating the module into a project, and one guide on the most common use case.

This content can start in the “Getting started” section of the index, and grow into this separate document as the module matures. If that document becomes too large, it can be replaced with a guides subdirectory containing more than one doc.

Interface docs (information-oriented)#

Pigweed AI summary: These interface docs provide information on a module's interfaces, with the option to omit them if there are no applicable interfaces. The SEED does not determine how API docs should be structured, generated, and maintained. Modules with APIs for multiple languages should have a separate directory for each language. The CLI and GUI tools should have their own documentation in cli.rst and gui.rst, respectively, with the CLI documentation closely matching the output of the "help" command.

These docs describe the module’s interfaces. Each of these docs may be omitted if the module doesn’t include an applicable interface.

`api.rst`: External API reference#

Pigweed AI summary: This paragraph discusses the importance of having reference documentation for user-facing APIs in modules. It suggests that modules with APIs for multiple languages should have separate documentation for each language. However, it also acknowledges that the process of structuring, generating, and maintaining API documentation is a complex topic that is not covered in this particular SEED.

Modules should have reference documentation for their user-facing APIs. Modules that have APIs for multiple languages should replace the single api.rst with an api subdirectory with docs for each supported language.

How API docs should be structured, generated, and maintained is a complex topic that this SEED will not determine.

`cli.rst` & `gui.rst`: Developer tools reference#

Pigweed AI summary: This paragraph discusses the documentation requirements for user-facing command line interfaces (CLI) and graphical user interfaces (GUI) in software modules. The CLI should be documented in a file called "cli.rst" and the documentation should closely match the output of the CLI tool's "help" command. The GUI documentation should be included in a file called "gui.rst" if the module provides a GUI.

A user-facing command line interface (CLI) should be documented in cli.rst if the module provides one. It’s ideal if this documentation closely matches the output of the CLI tool’s “help” command.

If the module provides a graphical user interface (GUI) (including text mode interfaces and web front-ends), its documentation should be included in gui.rst.

Tutorials (learning-oriented)#

Pigweed AI summary: This section is about learning-oriented tutorials that are kept as separate files in the tutorials folder. Although they require considerable effort to develop, they are not mandatory but are aimed to be developed for all modules except the most basic ones.

We keep these as separate files in tutorials. These take considerable effort to develop, so they aren’t required, but we aspire to develop them for all but the most trivial modules.

When one size does not fit all#

Pigweed AI summary: The article discusses the varying levels of complexity in Pigweed modules, from simple embedded libraries to more advanced communication protocols and developer tooling. The proposed structure for module documentation is suggested as a starting point, but modules with unique documentation needs are free to deviate from it by adding additional documentation.

Pigweed modules span a spectrum of complexity, from relatively simple embedded libraries to sophisticated communication protocols and host-side developer tooling. The structure described above should be the starting point for each module’s documentation and should be appropriate to the vast majority of modules. But this proposal is not strictly prescriptive; modules with documentation needs that are not met by this structure are free to deviate from it by adding docs that are not mentioned here.

Examples#

Pigweed AI summary: A template for implementing a specific structure can be found in the "docs/templates/docs" folder.

A template for implementing this structure can be found docs/templates/docs.