aego/docs/style.md

# Writing the Aego documentation

The site is read by people making games, not by people building the engine. Write what they see and what they do.

## Open every page the same way

- The first paragraph says what the page is about and when the reader needs it, in two to four sentences.
- Do not start with "In this guide we…". Start with the subject.

## Guides and references

- A guide explains how and why: it walks through a task.
- A reference lists: every field, function, flag or code, each with one short description.

## Say only what the reader needs

- Describe behaviour the reader can see or change. Leave out how it is implemented: buffer sizes, algorithms, internal packages and functions, decision numbers, log formats, release mechanics. Those belong in ARCHITECTURE.md or docs/contributing.md.
- Give a number only when the reader sets it or runs into it: a default they can change, a limit they can hit.
- Say a thing once. Link to the page that owns it instead of repeating it. A component page owns its fields; a guide links there.
- No filler: simply, just, easily, basically, of course, note that, please, in order to, it is important to.
- No history. Past tense and the history of decisions belong in ARCHITECTURE.md. Never write "we added", "in this stage", "this commit" or "the agent" about the work on Aego.

## Keep it short

- One fact per sentence. Split sentences joined by semicolons.
- A paragraph has at most four sentences. More than that is a list, a table or a new section.
- Steps the reader follows are a numbered list, one action per step.
- A bold phrase at the start of a paragraph is a heading. Use a heading.
- Start a page with one or two sentences: what it is and when to use it.

## Examples

- One idea, one example.
- Every code block is checked: `aes` blocks compile, `go` blocks are whole files that build against `sdk`.

## Name things the same way

- Address the reader as "you". Headings are nouns: "Rewinding", not "How to rewind".

- Use the terms in docs/glossary.md and the names the editor shows: Rigid Body 2D in prose, `physics.Body2D` in code.
- Menu paths in bold with arrows: **Window → Theme**. Keys in backticks: `Ctrl+Shift+A`.
- Field, method and event descriptions start with the verb, not the name: "Pushes the body…", not "ApplyForce pushes the body…". The site strips a leading name from Go doc comments, so code comments can keep Go style.
- Fields that only have values during Play are listed as runtime state; their description does not say "during Play".

## Write for translation

- Plain sentences without idioms, jokes or wordplay.
- One term for one thing across all pages.
- No sentences built from fragments that depend on English word order, such as "Click X to Y-ify it".

## Page types

| Type | Shape |
|---|---|
| Guide | what and when; steps; a table of options; See also |
| Concept | what it is; how it behaves; what the reader controls; See also |
| Component page | generated: summary, Usage, Fields, Runtime state, Methods, Signals, Script events, Related guides |
| Diagnostic | one sentence on what happened, then **Fix.** and one sentence on how to fix it, then an example that reproduces it |

## Before and after

Before: "Current velocity in units per second, during Play." with the flag "read-only during Play only".
After: "Velocity in units per second." under Runtime state.

Before: "OnCollisionExit runs when the bodies stop touching, including when one of them is destroyed or disabled. Contact.Point is the last known point."
After: "Runs when the bodies stop touching, also when one is destroyed or disabled. Contact.Point is the last point of contact."

Before: "How often depends on how heavy the game is: often enough that rewinding replays about 1.5 ms of game, but no more than every 30 ticks and no less than every 300."
After: "The editor keeps copies of the game along the timeline, so rewinding is quick even in long sessions."

## Checks

`aego docs check` reports these rules as warnings; `--strict` makes them errors. `aego docs report` lists every page with its findings, and a red row is a page with errors in strict mode.

| Code | Rule |
|---|---|
| DOC010 | Prose, outside code, matches a pattern of engine/docs/lint.aetext |
| DOC011 | A decision number (D123) or an internal package path in prose |
| DOC012 | A paragraph longer than 120 words |
| DOC013 | A paragraph that starts with a bold phrase ending in a period or colon |
| DOC014 | A field description longer than 160 characters or two sentences |
| DOC015 | A runtime field description that says "during Play" |
| DOC016 | A method, signal or event whose first sentence is longer than 160 characters |
| DOC017 | A sentence of 12 or more words that appears on two pages |
| DOC019 | A guide page without an opening paragraph before its first section |
| DOC020 | A name in backticks that looks like `Type.Member`, `pkg.Name` or `Call()` but names nothing in the reference |
| DOC021 | A component field without a description; always an error |
| DOC022 | A `go` block that gofmt cannot parse, that is a fragment, or that does not build against `sdk` |
| DOC023 | A diagnostic page whose "what" or "fix" part is not exactly one sentence |

A link to a page that does not exist (`ref:` to an unknown id) is always an error.

engine/docs/lint.aetext holds the DOC010 patterns, one `pattern` block each with `regex` (a Go regular expression, matched without case), `why` and an optional `skip_group`, a docs group where the pattern is allowed. It is embedded in `aego`, so an installed copy checks a project without the engine source. A page that needs a matched word in its own sense, such as "just pressed" on the input page, lists it in its front matter: `style_allow: [just]`.