1.. _seed-0102: 2 3===================================== 40102: Consistent Module Documentation 5===================================== 6.. seed:: 7 :number: 102 8 :name: Consistent Module Documentation 9 :status: Accepted 10 :proposal_date: 2023-02-10 11 :cl: 128811, 130410 12 :authors: Chad Norvell 13 :facilitator: Kayce Basques 14 15--------------------- 16Status (October 2023) 17--------------------- 18If you're looking for guidelines on how to author module docs, use these: 19:ref:`docs-contrib-docs-modules` 20 21.. caution:: 22 23 SEED-0102 is still considered accepted because we are still using some parts 24 of it in our current module docs guidelines. However, over the course of 25 2023 we discovered that other parts of the SEED-0102 plan didn't achieve our 26 goals. Therefore, at this point you should only read SEED-0102 for historical 27 context on how our docs guidelines have evolved. 28 29------- 30Summary 31------- 32Pigweed modules ought to have documentation that is reasonably comprehensive, 33that has a consistent and predictable format, and that provides the reader with 34sufficient information to judge whether using the module is the right choice for 35them. This SEED proposes a documentation philosophy applicable to all Pigweed 36modules and a flexible yet consistent structure to which all module docs should 37conform. 38 39Definitions 40----------- 41In this SEED, we define *users* as developers using Pigweed in downstream 42projects, and *maintainers* as developers working on upstream Pigweed. The 43primary focus of this SEED is to improve the documentation experience for users. 44 45---------- 46Motivation 47---------- 48Currently, each Pigweed module is required to have, at minimum, a single 49``docs.rst`` file that contains the module's documentation. This gives the 50module maintainer considerable discretion to provide as much or as little 51documentation as they would like. However, this approach fails for Pigweed 52maintainers by providing no guidance or structure to help them write effective 53documentation, and certainly fails Pigweed users who struggle to find the 54information they're looking for. So a solution needs to make it easier for 55Pigweed maintainers to write good documentation, thereby making Pigweed much 56more accessible to its users. 57 58Pigweed's design is inherently and intentionally modular. So documentation at 59the level of the *module* is the most natural place to make impactful 60improvements, while avoiding a fundamental restructuring of the Pigweed 61documentation. Module docs are also what the majority of Pigweed users rely on 62most. As a result, this SEED is focused exclusively on improving module 63documentation. 64 65`Diátaxis <https://diataxis.fr/>`_ proposes a four-mode framework for technical 66documentation, illustrated below with terminology altered to better match 67Pigweed's needs: 68 69.. csv-table:: 70 :widths: 10, 20, 20 71 72 , "**Serve our study**", "**Serve our work**" 73 "**Practical steps**", "Tutorials (`learning-oriented <https://diataxis.fr/tutorials/>`_)", "Guides (`task-oriented <https://diataxis.fr/how-to-guides/>`_)" 74 "**Theoretical knowledge**", "Concept & design docs (`understanding-oriented <https://diataxis.fr/explanation/>`_)", "Interface reference (`information-oriented <https://diataxis.fr/reference/>`_)" 75 76Pigweed needs a framework that ensures modules have coverage across these four 77quadrants. That framework should provide a structure that makes it easier for 78maintainers to write effective documentation, and a single page that provides 79the most basic information a user needs to understand the module. 80 81Alternatives 82------------ 83There are risks to focusing on module docs: 84 85* The most useful docs are those that focus on tasks rather than system 86 features. The module-focused approach risks producing feature-focused docs 87 rather than task-focused docs, since the tasks users need to complete may not 88 fit within the boundaries of a module. 89 90* Likewise, focusing on module documentation reduces focus on content that 91 integrates across multiple modules. 92 93The justification for focusing on module documentation doesn't imply that module 94docs are the *only* docs that matter. Higher level introductory and guidance 95material that integrates Pigweed as a system and covers cross cutting concerns 96is also important, and would arguably be more effective at bringing new 97developers into the Pigweed ecosystem. However, this SEED proposes focusing on 98module docs for two primary reasons: 99 1001. Improving module docs and providing them with a consistent structure will 101 have the largest impact with the least amount of investment. 102 1032. It will be easier to construct higher-level and cross-cutting documentation 104 from well-developed module docs compared to going the other direction. 105 106While not a primary consideration, a bonus of a module-focused approach is that 107modules already have owners, and those owners are natural candidates to be the 108maintainers of their modules' docs. 109 110-------- 111Proposal 112-------- 113This change would require each module directory to match this structure:: 114 115 module root directory/ 116 ├── docs.rst 117 ├── concepts.rst [or concepts/...] [when needed] 118 ├── design.rst [or design/...] [when needed] 119 ├── guides.rst [or guides/...] [when needed] 120 │ 121 ├── tutorials/ [aspirational] 122 │ ├── index.rst 123 │ └── ... 124 │ 125 ├── api.rst [or api/...] [if applicable] 126 ├── cli.rst [if applicable] 127 └── gui.rst [if applicable] 128 129Fundamental module docs 130----------------------- 131These three documents are the minimum required of every Pigweed module. 132 133The basics: ``docs.rst`` 134^^^^^^^^^^^^^^^^^^^^^^^^ 135Basic, structured information about the module, including what it does, what 136problems it's designed solve, and information that lets a user quickly evaluate 137if the module is useful to them. 138 139How it works and why: ``design.rst`` & ``concepts.rst`` (understanding-oriented) 140^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 141Background on the design goals, assumptions, limitations, and implementation 142details of a module, and may contrast the design of the module with alternative 143solutions. 144 145This content can start in the "Design considerations" section of the index, and 146grow into this separate document as the module matures. If that document becomes 147too large, the single ``design.rst`` file can be replaced by a ``design`` 148subdirectory containing more than one nested doc. 149 150Some modules may need documentation on fundamental concepts that are independent 151of the module's solution. For example, a module that provides a reliable 152transport layer may include a conceptual description of reliable transport in 153general in a ``concepts.rst`` file or ``concepts`` subdirectory. 154 155How to get stuff done: ``guides.rst`` (task-oriented) 156^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 157These are focused on specific outcomes and should be produced as soon as we see 158a question being answered multiple times. Each module should have at least one 159guide on integrating the module into a project, and one guide on the most common 160use case. 161 162This content can start in the "Getting started" section of the index, and grow 163into this separate document as the module matures. If that document becomes too 164large, it can be replaced with a ``guides`` subdirectory containing more than 165one doc. 166 167Interface docs (information-oriented) 168------------------------------------- 169These docs describe the module's interfaces. Each of these docs may be omitted 170if the module doesn't include an applicable interface. 171 172``api.rst``: External API reference 173^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 174Modules should have reference documentation for their user-facing APIs. Modules 175that have APIs for multiple languages should replace the single ``api.rst`` with 176an ``api`` subdirectory with docs for each supported language. 177 178How API docs should be structured, generated, and maintained is a complex topic 179that this SEED will not determine. 180 181``cli.rst`` & ``gui.rst``: Developer tools reference 182^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 183A user-facing command line interface (CLI) should be documented in ``cli.rst`` 184if the module provides one. It's ideal if this documentation closely matches the 185output of the CLI tool's "help" command. 186 187If the module provides a graphical user interface (GUI) (including text mode 188interfaces and web front-ends), its documentation should be included in 189``gui.rst``. 190 191Tutorials (learning-oriented) 192----------------------------- 193We keep these as separate files in ``tutorials``. These take considerable effort 194to develop, so they aren't *required*, but we aspire to develop them for all but 195the most trivial modules. 196 197When one size does not fit all 198------------------------------ 199Pigweed modules span a spectrum of complexity, from relatively simple embedded 200libraries to sophisticated communication protocols and host-side developer 201tooling. The structure described above should be the starting point for each 202module's documentation and should be appropriate to the vast majority of 203modules. But this proposal is not strictly prescriptive; modules with 204documentation needs that are not met by this structure are free to deviate from 205it by *adding* docs that are not mentioned here. 206 207Examples 208-------- 209A template for implementing this structure can be found ``docs/templates/docs``. 210