Skip to content

How to write docs

VeriLib uses a hub-and-spoke documentation model.

The rule

Where What
Your repo README.md = full module doc (source of truth)
Docs hub (this site) One page per module = title + link to repo README + short summary

If your README.md is good, the hub page takes about two minutes to add.

The exception: cross-repo contracts

Hub-and-spoke breaks down when something belongs to no single repo or has no upstream prose spec. Those are documented in full here, with the authoritative source file named at the top:

Page Why it lives here
Message contracts The wire format is a contract between four repos. The validate / promote shapes exist only as Python dataclasses.
Configuration and environment variables The failure modes are cross-repo mismatches, invisible from inside any one repo.
Probe ecosystem Spans nine repos with one shared schema.

If you find yourself writing a hub page that no repo could own, it probably belongs in this category — say so on the page.

Adding a hub page

  1. Create docs/components/{area}/{slug}.md (or the appropriate section folder).
  2. Add frontmatter: title, component, repo, status, last_reviewed.
  3. Include a link to the repo README as "Documentation source of truth".
  4. Add the page to nav in both mkdocs.yml and mkdocs-internal.yml. The internal config uses INHERIT: but MkDocs does not merge nav, so the two navs are maintained separately. Pages under docs/internal/ go in mkdocs-internal.yml only.
  5. Run mkdocs build -f mkdocs.yml --strict — CI does, and it fails on broken internal links.
  6. Open a PR — no doc update = not done for behavior-changing work.

Verify before you write

Upstream READMEs drift. Several pages on this site exist because a README disagreed with its own source — eth_certify's Contract API section documents functions that no longer exist in Certify.sol, and the atomize protocol doc's PROOF_LANGUAGE_ID_MAP default does not match the tracked deployment config.

When a repo's prose and its code disagree, read the code, document what is true, and say which source you checked. A dated !!! note "Unknowns" admonition is better than a confident guess.

Writing standards

Full conventions, templates, and review cadence live in the repository meta/ folder:

  • meta/documentation.md — documentation standard
  • meta/documentation-single-module.md — module README template
  • meta/component-list-complete.txt — master section list

Public vs internal

  • Public pages: safe for open-source contributors and external users.
  • Internal pages (docs/internal/): ops runbooks, server lists, credentials names only — never secret values. Built only with mkdocs-internal.yml and deployed behind OAuth2 Proxy.