Skip to content

Documentation Writing Guide

Use this as a short checklist when updating docs.

1) Keep Responsibilities Clear

  • Schema Navigation (generated): structure, quantities, relationships.
  • Schema Explanation (hand-written): rationale, invariants, usage guidance.
  • Do not duplicate generated reference content in explanation pages.
  • Add canonical links to relevant schema/*.md pages so generated schema docs can auto-link back to explanations.

2) Keep Pages Focused

  • Define a single primary question each page answers (for example: "how to model ModelSystem hierarchy").
  • Move secondary material to linked pages instead of expanding scope.
  • If two pages repeat more than a short paragraph, keep one canonical version and replace the duplicate with a link.
  • Prefer short sections with explicit headings.

3) Use a Simple Page Pattern

Use this structure for technical explanation pages (not required for overview/landing pages):

  1. Purpose
  2. Link to generated page(s)
  3. Rules/invariants
  4. Usage guidance (parser/normalization)
  5. Pitfalls and related links

4) Keep Examples Executable

  • Store snippets in docs/snippets/.
  • Include snippets via --8<-- "snippets/<path>/<file>.py".
  • Mark standalone runnable snippets with # docs-snippet: runnable.
  • Ensure every snippet has test coverage in tests/test_doc_snippets.py.
  • See docs/snippets/README.md for snippet categories and markers.

5) Assets and Paths

  • Store page-specific images in a local images/ folder.
  • Reference with ./images/<file> whenever possible.

6) Before Opening a PR

  • Run the docs generation pipeline if schema structure changed.
  • Update only affected explanation pages.
  • Check mkdocs.yml navigation paths/titles.
  • Verify links and docs build.