seed/0102-module-docs.rst

.. _seed-0102:

=====================================
0102: Consistent Module Documentation
=====================================

.. card::
   :fas:`seedling` SEED-0102: :ref:`Consistent Module Documentation<seed-0102>`

   :octicon:`comment-discussion` Status:
   :bdg-secondary-line:`Open for Comments`
   :octicon:`chevron-right`
   :bdg-secondary-line:`Last Call`
   :octicon:`chevron-right`
   :bdg-primary:`Accepted`
   :octicon:`kebab-horizontal`
   :bdg-secondary-line:`Rejected`

   :octicon:`calendar` Proposal Date: 2023-02-10

   :octicon:`code-review` CL: `pwrev/128811 <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/128811>`_, `pwrev/130410 <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/130410>`_

-------
Summary
-------
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
-----------
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
----------
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 <https://diataxis.fr/>`_ proposes a four-mode framework for technical
documentation, illustrated below with terminology altered to better match
Pigweed's needs:

.. csv-table::
   :widths: 10, 20, 20

   , "**Serve our study**", "**Serve our work**"
   "**Practical steps**", "Tutorials (`learning-oriented <https://diataxis.fr/tutorials/>`_)", "Guides (`task-oriented <https://diataxis.fr/how-to-guides/>`_)"
   "**Theoretical knowledge**", "Concept & design docs (`understanding-oriented <https://diataxis.fr/explanation/>`_)", "Interface reference (`information-oriented <https://diataxis.fr/reference/>`_)"

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
------------
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:

1. Improving module docs and providing them with a consistent structure will
   have the largest impact with the least amount of investment.

2. 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
--------
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
-----------------------
These three documents are the minimum required of every Pigweed module.

The basics: ``docs.rst``
^^^^^^^^^^^^^^^^^^^^^^^^
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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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)
-------------------------------------
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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)
-----------------------------
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 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
--------
A template for implementing this structure can be found ``docs/templates/docs``.