Skip to content

How to contribute

The handbook is open source and takes outside contributions. Pages are short, opinionated, and follow a fixed shape — this page covers what that means before you write one.

A topic earns a page when practitioners hit it repeatedly and a defensible default exists. If the honest answer is “it depends,” or a canonical external source already covers it well, it stays out — or gets a pointer instead of a page.

Every page must answer four questions quickly:

  1. What is this topic about?
  2. What is the recommended default?
  3. When should you do something different?
  4. What should you do next?

If a draft doesn’t answer these, it isn’t ready.

Pages follow the same order so readers know where to look:

  1. Short summary — one or two sentences on scope.
  2. Recommended default — stated as an instruction, not a description.
  3. Why this is the default — the tradeoff, in a short paragraph.
  4. Common mistakes or tradeoffs — bulleted, each with “do this instead”.
  5. Step by step — concrete actions, numbered.
  6. Related — only include if every link resolves to an existing page.

Not every section is mandatory on a short page, but the order stays the same. The Development section is the closest thing to a worked example — new pages should feel at home next to it.

  • State the default, then the exception. “Squash on merge — unless the branch tells a story worth keeping.”
  • Short paragraphs, concrete verbs. Cut in order to, please note, it should be noted.
  • Take a position. “It depends” is not a handbook.
  • British English. Organise, behaviour.
  • One A4 page or less (≈ 500 words). If it’s longer, split it.

The full authoring guide lives in docs/TONE.md in the repository.

  1. Fork the repository and clone your fork.
  2. Create a branch. Use draft: true in the frontmatter while iterating — draft pages render in npm run dev but are excluded from the production build.
  3. Run npm run dev and check the page appears in the sidebar, search finds it, and internal links resolve.
  4. Run npm run build — the build fails on broken links, so it doubles as a review step.
  5. Open a merge request. Keep it small enough to review in one sitting.

Full setup details, the page template, and the frontmatter reference live in CONTRIBUTING.md at the root of the repository.

The handbook is licensed under Creative Commons Attribution-ShareAlike 4.0 International. By contributing, you agree to license your contribution under the same terms.

Open an issue if you’re unsure whether a topic fits the handbook, or whether the recommended default should differ from what a page currently says.