Skip to content

Writing Jezero's documentation

How the docs are organised and written, so every page feels like part of one book.

Four kinds of page

The docs follow Diátaxis: each page does one job, and the folder says which.

Folder Kind The reader... The page...
getting-started/ Tutorial is learning takes one guaranteed path, start to finish, with no choices to make
how-to/ How-to guide has a goal starts from the goal, gives numbered steps, mentions alternatives
reference/ Reference is looking something up is complete, terse and consistent; generated from code where possible
explanation/ Explanation wants to understand explains why, the trade-offs and what was rejected

If a page starts doing a second job, move that part to the page that owns it and link to it. A tutorial that stops to list every option, or a reference page that tells a story, is the usual sign.

Shape of a page

  1. # Title: a noun phrase for reference and explanation ("Configuration", "How search ranks results"), the task for how-to guides ("Connect an agent").
  2. One or two sentences under the title: what the page gives the reader.
  3. ## Before you start, when something must already be in place: link to it.
  4. The body.
  5. ## Next steps (tutorials, how-to) or ## See also (reference, explanation): two to four links, each with a few words on why to go there.

Voice

  • English, second person, present tense, active voice: "Jezero stores", "you run".
  • Short sentences. One idea per paragraph. No filler ("simply", "just", "easy").
  • Name things the same way everywhere (see the glossary). In the docs an entry of the library is an item; the app calls it a memory.
  • No em dashes: use a colon, a comma or a new sentence.
  • Wrap prose at about 90 characters, as the rest of the repository does.

Commands and examples

  • Every command is copyable: a fenced block with a language (bash, toml, json), no $ prompt, one command per line.
  • Show what the reader should see in a separate block introduced by "You should see:". Trim long output with ....
  • Placeholders are uppercase: https://YOUR-JEZERO, DEVICE, SHA256. Never a real host, address, path or name: examples use /home/me, the devices laptop and work-mac, and the projects atlas, billing and shop.
  • Secrets are never shown. Refer to them by their variable (api_key_env) or as Bearer ***.
  • Every command, flag and option on a page has been checked against the code, and run when possible (in a temporary HOME, never against a real installation).

Callouts

GitHub alerts, sparingly, at most two per screen:

> [!NOTE]
> Context that is useful but not essential.

> [!WARNING]
> Something that loses data, leaks a secret or breaks an agent.
  • Relative links between pages (../reference/cli.md#jezero-run).
  • Link the first mention of a concept on a page to its reference or explanation.
  • reference/cli.md and reference/configuration.md are generated by scripts/make_reference.py from the code: change the code (its help text or docstrings), then run the script. CI fails if they are out of date.