Docs writing guide

Docs are part of the product. A reader should be able to trust every sentence, so we write plainly and only claim what the code does today.

Tone

• Plain and direct. Short sentences. Say “use”, not “utilize”.
• Talk to the reader: “you”, and imperative verbs for steps (“Run the command”).
• Explain a term the first time it appears, or link to Concepts.
• No hype, no marketing adjectives (“powerful”, “seamless”, “blazing fast”).
• Be honest about limits. A known limitation stated clearly helps more than a gap left for the reader to discover.
• Use inclusive language and avoid idioms that do not translate well.

Structure

Each page does one job. Pick one:

Rules for every page:

• Start with one or two sentences saying what the page covers and who it is for.
• One # title (the layout adds it from the title frontmatter), then ## and ### in order. Do not skip levels.
• Put prerequisites before the steps that need them.
• Keep paragraphs short. Prefer a list or table when content is parallel.
• Link text says where the link goes (“see the sandbox page”), never “click here”.
• Write file names, commands and option names in code font.
• Mark anything unfinished with TODO: so it is easy to search for. Do not publish guesses as fact.

Adding a page

1. Create a Markdown file under src/pages/docs/, for example src/pages/docs/guides/backup.md.
2. Start it with frontmatter: layout (copy it from a neighbouring page, adjusting the relative path), title and description.
3. List the page in src/data/docs.ts so it appears in the navigation.
4. Run pnpm check and pnpm build, then pnpm dev and read the page in the browser.

What we do not promise

Documentation is read as a commitment. Do not write any of these:

• Features that are not released. Document what exists in the current release. Plans belong on the roadmap, not in the docs.
• Dates or versions for future work. No “coming soon” and no “next quarter”.
• Absolute security claims. Never “secure”, “safe”, “unhackable” or “fully isolated”. Describe what a mechanism does and what it does not cover: “The sandbox blocks writes outside the project folder. It does not limit network access.”
• Privacy or compliance claims (for example “GDPR compliant”, “your data never leaves your machine”) unless the legal and security owners have reviewed the exact wording.
• Performance numbers without a published, repeatable measurement.
• Compatibility with an operating system, version or tool we do not test.
• Prices, plans or hosted-service terms outside the pricing page.
• Support or response times, and anything that sounds like a warranty.
• Third-party behaviour. Link to their docs instead of describing what they do.

If you are not sure a statement is true, check the code or ask the owner. If it still cannot be confirmed, leave it out or mark it TODO:.

Examples

Every example must work, and we know it works because it is run.

• Commands and code come from tested sources. The single source of truth for runnable examples is an example file in the main Halonic repository that its test suite runs. Copy from there rather than typing from memory.
• Show the output a reader should see, so they can tell it worked.
• Use fake values only: example.com, my-project, obviously made-up names. Never include real keys, tokens, passwords or personal data.
• Label illustrations. A snippet that is not run, such as a sketch of a config shape, is introduced with “Illustration, not runnable:”.
• Pin what matters. If an example depends on a version, say which one.
• Check before merging. Run each example against the release the page describes, and say so in the pull request.

Automatic checking of examples (extracting them from the docs and running them in CI) is planned once the new monorepo has runnable examples. Until then the author’s check in the pull request is the control.

Review checklist

Before opening a pull request, confirm:

• The page has one clear job and says so in its first lines.
• Every claim matches the current code or release.
• Nothing from the do-not-promise list is in the text.
• Examples were run, use fake values, and show their output.
• The page is in src/data/docs.ts and pnpm check and pnpm build pass.