write-docs

# Write Docs

A short, living set of rules for writing documentation in this repo. Update as we learn what works.

## 0. Write for a reader in a situation

This rule governs every other rule below. Every failure in a doc review traces back to breaking it.

Your reader is a **stranger with a job to do**. They are not your teammate, they did not read the PR, they do not know the codebase, and they do not care about your reasoning. They arrived with a situation and a question. Serve that, nothing else.

Some readers are agents, some are humans. Write for both: an agent needs unambiguous structure, a human needs to find their case fast. Neither needs your narration.

### The four beats

For anything non-trivial (a troubleshooting entry, a decision, a procedure with branches), give the reader these in order. Do not overdo it on simple content.

1. **Context.** What is the situation? Stated plainly, so I can tell whether I am in it.
2. **Relevance.** Is this me? Do I need to act? Let me self-select out fast.
3. **Instructions.** Exactly what to run or change. Concrete, copy-pasteable.
4. **References.** Links to go deeper, if it is complicated.

A section that says "enable the tunnel profile" without telling me *how* has skipped beat 3. A warning that does not tell me whether it applies to me has skipped beats 1 and 2.

### Never assume things about the reader

Do not tell readers what they think, what they usually get wrong, or what their first question is. You do not know them, and the sentence serves you, not them.

- BAD: "This is the part teams usually get wrong."
- BAD: "This is the first question a self-hosting community asks."
- BAD: "You probably want X."
- GOOD: State the fact. Let them decide if it is their case.

### No opinions, no value judgments

Docs state facts and give instructions. They do not give advice you were not asked for, and they do not editorialize.

- BAD: "Keep CPU and memory generous."
- BAD: "This is the right way to do it."
- GOOD: "The default is 2 CPU / 4 GB. To change it, set X."

If a constraint is real, state it as a constraint ("the idle TTL must be below AUTOSTOP, or Daytona stops a sandbox the runner still holds"). That is a fact, not an opinion.

### Only the reader's problem belongs on the page

Cut anything that is not the reader's concern in *their* situation.

- In a how-to for running agents on Daytona, the **code evaluator's** sandbox is not the reader's problem. It confuses them. If the fact matters, it belongs in reference.
- Do not pre-empt failure modes the reader cannot hit. If you just told them to run the snapshot recipe, do not then warn "if the image is missing Pi…". They followed your instructions. It will not be missing.

Ask of every sentence: **in the situation this page is for, does the reader need this?** If not, delete it or move it to reference.

### Parallel things get parallel structure

If two options exist (Daytona and local; Compose and Helm), give them **mirrored sections with the same sub-structure, in the same order, on every page**. A reader learns the shape once and then navigates by it.

- Nest correctly. "What crosses into the Daytona sandbox" belongs **under** Daytona, not floating at the top level.
- If you write a subsection for one option, write the matching one for the other, or explicitly say it does not apply.
- Lead with the option you want most people to use.

### An instruction without a concrete example is not an instruction

"Add your dependencies" tells the reader nothing. Name a plausible thing and show the line. The
reader adapts an example far faster than they invent one from a description.

- BAD: "Add your dependencies to the recipe."
- GOOD: "Add your dependencies to `dockerfile_commands`. For example, the `gh` CLI and Chromium: `RUN apt-get install -y gh chromium`."
- GOOD: "Mount a repository checkout so agents can work on it: `- /srv/repos/my-service:/agenta/workspaces/my-service:rw`. Use `:ro` when they should only read it."

### Use the precise word, not the dramatic one

Vague adjectives, especially security ones, make the reader guess. Say the condition that is
actually true.

- BAD: "Use Daytona when your deployment is exposed." (Exposed to what? Does that include me?)
- GOOD: "Use Daytona when more than one person can start runs on the deployment."
- BAD: "Local runs are not safe."
- GOOD: "Local runs are not isolated from each other. One user's agent can read another's files."

### A pointer is a sentence, not a section

If the answer is "go read that other page", write one sentence with the link where the reader hits
the question. Do not give it a heading and three paragraphs of setup. A section promises content.

### Slugs exist to preserve URLs

Add a `slug:` to a page's frontmatter only when the file moved and the old public URL must keep
working, or when the natural path is wrong. Never add one just because other pages have one.

### Verify every instruction against the thing it instructs

Prose discipline is not enough. An instruction you did not check is a lie with good grammar, and it
costs the reader an afternoon.

Before you write "set X in your values file", open the chart and confirm the key exists. Before you
write "add a `COPY` step", confirm the build has a local context. Before you name an env var,
confirm the code reads it. Before you claim "everything else is documented above", go count.

Real failures caught in review, all of which read fluently:

- BAD: "For Helm, add the volume to the runner pod in your values file." The chart renders **no**
  user volumes and `values.schema.json` has no volumes key. The instruction is impossible.
- BAD: "Copy files in with a `COPY` step." The snapshot recipe uses `dockerfile_commands()` with no
  local build context, so `COPY` cannot work. `RUN git clone` can.
- BAD: "Every other variable the runner reads is documented above." It reads about forty more.

If you cannot verify a claim, do not write it. Cut it, or go read the code.

###