Skip to content

Writing docs

A short style guide so the wiki stays useful as it grows.

Structure

One topic per page. If you're about to add a third H2 that feels like a different subject, split it into a new page and link between them.

Lead with the answer. Put the "TL;DR" or the thing people came for in the first paragraph. Background and caveats go below.

Write for the reader at 2am. Most wiki traffic is someone trying to solve a specific problem under time pressure. Assume they'll skim.

Voice

  • Second person ("you run the migration") reads better than passive ("the migration is run").
  • Present tense. "The CI pipeline builds the image" not "will build."
  • Short sentences. If a sentence has two ideas, it's two sentences.

Markdown conventions

Use admonitions for important callouts:

!!! warning "Data loss"
    This command drops the table. Make sure you have a backup.

!!! tip
    Pair this with `--dry-run` the first time.

Which render as:

Data loss

This command drops the table. Make sure you have a backup.

Tip

Pair this with --dry-run the first time.

Use fenced code blocks with a language tag so syntax highlighting works:

```python
def hello():
    print("hi")
```

Linking

  • Link to other wiki pages with relative paths: [deployments](../processes/deployments.md).
  • When you mention a tool, service, or concept the first time on a page, link to its page or its docs.
  • Don't link the phrase "click here." Link the noun: "see the [deployment runbook]."

When a page goes stale

Every page has a "last updated" date at the bottom (from git history). If you notice something is wrong, fix it in the same PR you noticed — even if it's not "your" area. That's the whole point of the wiki being a repo.