Living Documentation
Goal: Build a documentation system that ensures all documentation is relevant, correct, and sufficient.
Justification: The usefulness of documentation is dependent on its correctness and comprehensiveness. Identifying and fixing instances of irrelevant, incorrect, or insufficient documentation allows us to trust our docs as a source of truth.
Components:
- Documentation schema. Where is our documentation located, and what defines a syntactically valid piece of documentation?
- Tests for relevance. How can we ensure that all pieces of our documentation relate to one or more things that exist in our repo?
- E.g. Require headers link to other files, ensure that documentation is updated appropriately if a dependency is moved or deleted.
- Tests for correctness. How can we ensure that our documentation is kept up to date with the components to which it relates?
- E.g. Require that documentation is updated when a dependency is modified.
- E.g. Ask AI to rate the correctness of assertions in docs.
- Tests for comprehensiveness. How can we ensure that all components are documented?
- E.g. Ensure all directories contain a valid README.md file.
- E.g. Ensure documentation compiles to a tree without islands or orphans.
- E.g. Ensure all code is linked to one or more docs.
No due date
0% Completed
