Write and review guides¶

This project uses one editorial standard and one information-architecture model:

Follow the Google developer documentation style guide for wording, grammar, procedures, code examples, links, and accessibility.
Use Diátaxis to decide whether a page is a tutorial, how-to guide, explanation, or reference.
Consult the Microsoft Writing Style Guide only for inclusive-language or accessibility questions that Google does not answer.

When guidance conflicts, Google style controls the wording. Do not blend sentence-level conventions from multiple style guides.

Know the page type¶

Type	Reader need	Example in this project
Tutorial	Learn through a guided experience	Implement BM25 from scratch
How-to	Complete a specific task	Enable hybrid retrieval
Explanation	Understand a design or concept	Retrieval trust boundaries
Reference	Look up exact facts	Environment variable reference

The numbered guide series consists of tutorials. Keep reference tables and broad architecture explanations on separate pages, then link to them when needed.

Write for this reader¶

Assume the reader:

Writes Python and can use a command line.
Has not built an application with a language model.
Wants to understand the implementation, not only copy it.
Uses Windows, macOS, or Linux.

Define a new AI term when it first appears. Introduce no more than three new concepts in one guide unless the curriculum records a deliberate exception.

Follow the tutorial structure¶

Use these sections in order when they apply:

What you'll build states the observable outcome and estimated time.
Before you begin lists software, keys, and prerequisite guides.
See it work gives the reader a concrete result before the explanation.
How it works explains only the concepts needed for the procedure.
Build the feature presents ordered, testable steps.
Verify your work proves the result with focused checks.
Break it on purpose demonstrates one meaningful limitation.
Troubleshooting separates observed failures from predicted ones.
Next steps links the next guide and primary external documentation.
Tested against records versions and the verification date.

Use task-oriented titles such as “Implement Okapi BM25 from scratch,” not topic titles such as “About BM25.”

Make procedures usable¶

Address the reader as “you.”
Use active voice and present tense.
Begin each numbered step with an imperative verb.
Put the file or location before the action.
Keep one action in each numbered step.
Explain the expected result immediately after the action.
Indent continuations of numbered items with four spaces. Three spaces split the procedure into separate lists in MkDocs.
Avoid “easy,” “simply,” “just,” “obviously,” and directional phrases such as “below.”
Use repository-relative paths in prose and output.
Show PowerShell and Bash when commands differ.
Keep secrets out of commands, output, screenshots, and fixtures.

Account for every command¶

Every shell block in docs/guides/ requires one annotation immediately before it.

Use a machine-checkable command when it is safe and deterministic:

<!-- verify cmd tier=offline -->

```powershell
uv run pytest tests/test_rag_bm25.py -q
```

<!-- verify expect match=contains -->

```text
4 passed
```

Set output=none only when success is represented entirely by the exit code:

<!-- verify cmd tier=offline output=none -->

```powershell
uv run ruff check app/rag/index_bm25.py
```

Mark destructive or inherently visual steps for human verification:

<!-- verify manual reason="Modifies the temporary tutorial workspace" -->

```powershell
Clear-Content app/rag/index_bm25.py
```

A manual annotation is an explicit review obligation, not a passing automated check. Never run destructive tutorial steps in the repository checkout; future scenario verification will use a temporary workspace.

Use verification tiers¶

offline commands require no API key, network call, or paid service.
keyed commands call Anthropic or Voyage and run only through an approved environment.

Do not require exact generated prose from a model. Verify deterministic structure, source IDs, configuration, or sanitized metadata instead.

Cite measured facts¶

Declare every stable numerical claim in guides/plan.json, then wrap the value shown to readers with its dotted ledger path:

The corpus contains
<!-- fact corpus.chunk_count -->267<!-- /fact --> chunks.

harness.measure_facts derives docs/facts.json from repository behavior. harness.verify_facts fails when the committed ledger drifts, a displayed value is wrong, a guide uses an undeclared fact, or a declared fact is not displayed. Keep exact BM25 scores out of the ledger because unrelated corpus changes can move them without changing the lesson.

Preserve the learning flow¶

Declare prerequisite IDs in guides/plan.json and link every available prerequisite in the guide's Before you begin section.
Add published and draft guides to MkDocs in curriculum order. MkDocs renders that order as the previous/next footer, so older articles do not need edits whenever a later article is generated.
Keep a Next steps section in every tutorial. Link guides that already exist, but mention planned guides without creating dead links.
Keep guide H1 text identical to the curriculum title and use descriptive file names for stable URLs.
When renaming a published guide, add its old Markdown path to the MkDocs redirect_maps configuration so existing bookmarks continue to work.

Review a guide¶

Confirm that:

The learning outcome is observable.
Every stated number or ranking was measured.
Every shell block is verified or has a specific manual reason.
The guide introduces only its declared concepts.
Commands work from the repository root.
Expected output excludes absolute paths, timing, and temporary names.
Internal links resolve and the page appears in mkdocs.yml.
python -m harness.verify_guides "docs/guides/*.md" --execute --root . passes.
python -m harness.verify_facts --root . passes.
python -m harness.verify_guide_flow --root . passes.
mkdocs build --strict passes in CI.

Machine verification establishes factual consistency. A human reviewer still decides whether the guide teaches clearly.

Review documentation impact¶

Each published guide declares its implementation ownership in primary_code in guides/plan.json. Guide checks compare changed files with those declarations and add an advisory pull-request summary naming guides that might need review. The report does not block a merge: it prompts the reviewer to decide whether the code change changes the tutorial's explanation, commands, or facts.

Check the rendered site¶

Install the browser test dependencies once:

npm ci
npx playwright install chromium

Build the site and run the desktop and mobile smoke tests:

mkdocs build --strict --site-dir site
npm run test:docs

The smoke tests discover rendered content pages, require a visible primary heading, verify that Mermaid source becomes a nonempty SVG, and reject page-level horizontal overflow on mobile. Failed runs retain screenshots, traces, and an HTML report in CI.