Write and maintain docs¶

Goal. Contribute accurate, well-placed documentation — a new page, an update to an existing one, or a new ADR.

How the site is organized¶

The docs live in docs/ and are built with MkDocs into a site at https://harvard-lil.github.io/binoc/. The top-level nav is organized by audience (Users, Plugin Developers, Core Developers). Within each audience section, pages follow Diátaxis mode:

Mode	Directory	Use when…
Tutorial	`docs/tutorial.md`	Learning-oriented, concrete. Shows a beginner succeeding. Generated by Showboat — do not hand-edit.
How-to	`docs/howto/`	Doing-oriented, concrete. Solves one task for a reader who knows what they want.
Reference	`docs/reference/`	Doing-oriented, abstract. Exhaustive, accurate, dry. Most reference pages are generated — see below.
Explanation	`docs/explanation/`	Learning-oriented, abstract. Builds understanding; links into ADRs rather than restating rationale.
ADRs	`docs/adr/`	Architectural decisions: context, decision, alternatives, consequences.

Don't mix modes on one page — that's the single most reliable way to produce bad docs. When in doubt, split.

Generated pages — don't hand-edit¶

These are regenerated from authoritative sources; edits will be overwritten:

Page	Generator	Recipe
`docs/tutorial.md`	Showboat (re-runs embedded shell)	`just docs-tutorial`
`docs/reference/cli.md`	`clap_markdown` from `binoc-cli`	`just docs-cli`
`docs/reference/python.md`	`mkdocstrings` from `binoc-python` docstrings	built at site-build time
`docs/reference/changeset-schema.md`	`schemars` from Rust IR types	`just docs-schema`
`docs/explanation/test-vectors-gallery.md`	`scripts/build_test_vector_gallery.py`	`just docs-vectors`

If any of these are stale, just docs (the aggregate recipe) brings everything up to date.

Adding a new page¶

Create the file in the right directory (see table above).
Add frontmatter at the top:
```
---
audience: <primary audience>
---
```
Primary audiences: data steward, pipeline integrator, plugin author, core contributor, release manager.
Add it to the nav in mkdocs.yml. The build is strict — an orphan page (present in docs/ but absent from the nav) fails CI.

Verify:

just docs-build    # fails on broken links or orphan pages
just docs-serve    # live preview at 127.0.0.1:8000

Authoring conventions¶

Every page is page one. Most readers arrive from search, not the nav. Open with what the page is for and who it's for; link to prerequisites inline rather than assuming the reader has read upstream pages.

How-to titles are task-oriented. "Write a Python comparator" beats "The Python plugin API." How-to titles are written for search.

Mermaid for diagrams. pymdownx.superfences renders mermaid natively. Use hand-authored SVG only when mermaid is genuinely insufficient.

Code samples should be runnable. Where possible, cite snippets from test-vectors/ or docs/examples/ rather than embedding code that drifts. Note that test-vectors/ ships source trees, not built artifacts — how-tos that demo a vector should ask the reader to run just materialize first.

Link to ADRs; don't restate rationale. When an ADR is canonical for a concept, link to it. Short prerequisite restatements are fine; full parallel explanations are not (ARID over DRY).

No per-page stability badges. The site-level "in active design" banner covers it. Revisit when a surface stabilizes.

Writing an ADR¶

ADRs are the canonical record of design decisions — especially rejected alternatives. Write one when a decision's rationale or alternatives are non-obvious from the code.

Format:

---
audience: core contributor
---

# <Short decision name>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Superseded by [foo](foo.md)

## Context

## Decision

## Alternatives Considered

## Consequences

Conventions:

File names use snake_case.md.
Cross-reference other ADRs with relative markdown links — the strict build validates them.
When an ADR supersedes an earlier one, update the older ADR's Status line to Superseded by [new-adr](new-adr.md).
Add the new file to the nav in mkdocs.yml under For Core Developers → Architectural decisions.

Build and preview¶

just docs            # regenerate all generated inputs
just docs-serve      # live preview at 127.0.0.1:8000 — hot-reloads on save
just docs-build      # strict build, mirrors CI

CI runs just docs && just docs-build on every PR. A broken link or orphan page fails the build.