-
Notifications
You must be signed in to change notification settings - Fork 120
Documentation Standards
This page is the contract for writing here, so that nobody has to second-guess how a page should be written, formatted, or placed.
This wiki documents Triad as it runs today: how to operate its systems, what their moving parts are, and why they are shaped the way they are. It is informational only.
| The thing you have | Where it goes instead |
|---|---|
| A proposal, design doc, or balance discussion | a GitHub issue or Discord |
| A work item with an owner and a state | a GitHub issue |
| Teaching a new player how to play | the in-game guidebook |
| A PR description, changelog, or session notes | the PR and the changelog |
If the thing is not built yet, it does not have a page here yet.
Four kinds, borrowed from Diátaxis. Every page is exactly one of them; mixing modes on one page degrades all of them.
| Kind | Answers | Shape |
|---|---|---|
| Guide | "How do I…?" | goal-titled gerund ("Running the Edison Supermatter"), steps in the order you perform them, "you" |
| Reference | "What is…?" | mirrors the system's structure, facts and tables, no instructions, ends with a "Where the code lives" table |
| Explanation | "Why…?" | topic-titled, history and connections, may hold opinion, no field lists |
| Index | "Where is…?" | pointers only |
If a draft resists the split, it is two pages. Split it.
File names. Title-Case-Words-Hyphenated.md; GitHub renders the name as the title, hyphens as spaces.
Important: ASCII only, and never a colon. A colon cannot exist in a Windows filename, so one badly named page breaks cloning the whole wiki on Windows. A Unicode hyphen looks identical to
-while breaking every link written with the ASCII one.
Headings. No H1 (the file name is already the title). H2 for sections, H3 for subsections, never H4. Sentence case. A heading that needs a separator uses a colon, never a dash.
Opening. One to three sentences stating what the page covers. Never a heading called "Introduction" or "Overview".
Callouts. Exactly two flavors: > **Note:** for something true and surprising, > **Important:** for something that breaks if you get it wrong. At most about one per section.
Tables, code, links. Tables for three or more parallel items, cells as fragments. Backtick every path, type, cvar, prototype id, and YAML key; paths repo-relative. Fenced blocks get a language tag and stay short. Internal links use the page file name, no extension, no URL: [Documentation Standards](Documentation-Standards); never "here", never a bare URL.
Numbers and dates. Space between value and unit (3072 m), none before %, thousands separators from four digits (1,800 moles). Every tunable number names its knob: "3072 m (describe_range)". Dates are ISO YYYY-MM-DD.
Diagrams and images. Mermaid renders natively; use one when the topology is genuinely a graph. Images live in this repo under images/, named <page-file-name>-<subject>.png.
- Numbers come from the code, never from memory. When a subsystem changes, updating the pages that describe it is part of the same work, not a follow-up.
- Home is the index. Every live page appears there exactly once, grouped by kind, with a one-line hook. Adding the link is part of creating the page.
- Renames and replacements. Reduce the old page to one sentence pointing at the new one, drop it from Home, and never delete it; external links still point there.
-
Commits. Lowercase scope prefix, imperative mood, one logical change each:
edison: re-verify the payout curve. Pull before you write.