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/. Both the on-disk layout and the nav are organized by audience first, then by Diátaxis mode: docs/<audience>/<mode>/<page>.md, and the nav: in mkdocs.yml mirrors that tree one-to-one. The three audiences are nested subsets, not disjoint — Users ⊇ Plugin authors ⊇ Core developers — so place each page at its highest level of generality: the broadest audience that needs it.

Audience directory	Place a page here when…
`docs/users/`	it helps any reader diffing datasets (this includes plugin authors and core devs).
`docs/plugin-developers/`	it is only useful once you're extending binoc with a rule pack or renderer.
`docs/core-developers/`	it only matters to someone changing the engine itself.

Within each audience, pages follow Diátaxis mode:

Mode	Subdirectory	Use when…
How-to	`<audience>/howto/`	Doing-oriented, concrete. Solves one task for a reader who knows what they want.
Reference	`<audience>/reference/`	Doing-oriented, abstract. Exhaustive, accurate, dry. Most reference pages are generated — see below.
Explanation	`<audience>/explanation/`	Learning-oriented, abstract. Builds understanding; links into ADRs rather than restating rationale.

A few areas sit at the top level instead: docs/tutorial.md (learning-oriented, concrete — generated by Showboat, do not hand-edit), docs/adr/ (architectural decisions; kept at a stable path because source and config cite it, and surfaced under For Core Developers in the nav), and the generated docs/sdk/ rustdoc.

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/users/reference/cli.md`	`clap_markdown` from `binoc-cli`	`just docs-cli`
`docs/users/reference/third-party-plugins.md`	`scripts/build_third_party_plugins_page.py`	`just docs-plugin-catalog`
`docs/plugin-developers/reference/python.md`	`mkdocstrings` from `binoc-python` docstrings	built at site-build time
`docs/users/reference/changeset-schema.md`	`schemars` from Rust IR types	`just docs-schema`
`docs/users/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 at docs/<audience>/<mode>/<name>.md — pick the broadest audience that needs it, then the mode (see tables 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 Rust rule pack" beats "The Rust 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.