Keep the docs current¶

The reference pages describe behavior, so a change to the code can make a page wrong. Treat the docs as part of the change:

1. Before you open a pull request, run rake docs:stale. It lists each page whose sources you changed while the page didn't change. Read each page it names, and update what your change made wrong. A page that's still right needs no edit. CI prints the same list as warnings on the pull request.
2. When a page starts or stops describing a file, add it to or remove it from the page's sources. A source can be a file or a directory.
3. When you add a page or change a page's title or description, run rake docs:index to regenerate the page lists in every index.md.
4. Run rake docs:check. It fails on a page without type, title, or description, on a source that doesn't exist, and on an index that's out of date. CI runs it on every push, and so does rake.

Frontmatter¶

Each page starts with Open Knowledge Format (OKF) frontmatter:

• type: Reference for a page that describes behavior, Glossary for the terms, Design for the rationale, and Contributing for the pages about working on Hot Cell itself.
• title and description: the page's name and one-line summary, which the section's index lists.
• order: optional. An index lists the pages that have an order first, in that order, and the rest by file name.
• sources: the code that the page describes. When that code changes, the page might need to change too.

Tables held to the code¶

Some tables are held to the code by tests, which fail when the two disagree: