Documentation standards - NexusTomorrow/server GitHub Wiki

The contract for writing on this wiki, so nobody has to second-guess how a page should be written, formatted or placed. Every page answers two questions before its first sentence: what kind of page it is, and how much you should trust it. How the words and markup look is on Documentation standards house style.

This wiki holds two different things: documentation of what's built, and thinking about what we intend to build. A server core being built from the ground up has a lot of the second, so they need different rules, and we borrow one framework for each.

Diátaxis decides what kind of page you're writing. It splits documentation on two axes, action versus cognition and acquisition versus application, and argues that the four quarters cover everything documentation can be. Its core claim is that mixing modes on one page degrades all of them, because each mode serves a reader in a different state. We use it for everything that describes something that exists.

The RFD process decides how much a page can be trusted. Oxide's take on Rust RFCs and architecture decision records attaches an explicit state to each document, from a rough idea through to built. It exists because a written design reads as authoritative whether or not anyone agreed to it or built it. We use its state ladder for everything that describes intent.

Diátaxis has no slot for a design, because a design isn't documentation of a product; it's a record of a decision. That gap is where the RFD half lives. Kind governs a page's shape, and status governs its authority.

Three kinds of reader come here: contributors working on the code, operators hosting a server, and anyone following the design. A guide is written for one of the first two, and says which in its opening paragraph.

Five kinds. Every page is exactly one of them.

A guide takes a reader who already knows what they want and walks them to it. It's a sequence of actions, not a tour of the machinery.

• Title it after the goal, as a gerund: "Running the tests".
• Steps go in the order the reader performs them, including the waiting.
• Handle real conditions with conditional imperatives: "If the run fails before the test step, open its log, not the results."
• Don't teach and don't enumerate. If a step needs a fact, state it and link the reference page that owns it.
• A guide may hold opinions about practice, because operating advice is the product.

Reference describes the machinery. It's led by the thing it documents, not by what a reader wants to do.

• Its structure mirrors the system's structure. One chapter per component or phase, in the order the code runs them. If the code is reorganized, the page is reorganized.
• It's austere. State the fact, not the reason and not the recipe, and link out for both.
• Tables are the default shape for anything enumerable: fields, opcodes, flags, ports, projects.
• Every reference page ends with a "Where the code lives" table: piece and path, paths in backticks and repo-relative. So does every other page with a ref badge, because that table is how a changed path finds the pages that describe it.
• No instructions. If you find yourself writing "you should", you're writing a guide.

Explanation is the only kind that may argue. It carries the why: constraints, alternatives, and how the pieces hook together.

• Title it as a topic, not a task. The implicit framing is "about X".
• Connections between parts of the server belong here, and so does vocabulary.
• It may hold opinion and name what was rejected, as long as it describes something that exists.
• Keep its boundary honest. The moment it starts listing fields, that content belongs on a reference page.

A design page is a proposal, a decision, or a record of one. It's the only kind allowed to describe something that doesn't exist.

• If it isn't built, it's a Design page. That rule settles most placement doubt, and on this project it covers most of the server.
• Title it after the system plus "design". Roadmap is the one exception: it's the design for the order of the whole build.
• It states decisions as locked or open, and records what was rejected with the reason or measurement that killed it. Negative results stop the next person spending a week re-deriving them.
• It carries a status from the ladder, and it's expected to move.

Home and this page. An index holds pointers and the rules for reading them, and no content that could go stale on its own.

A tombstone is a special index page: a renamed page reduced to one sentence pointing at its replacement. Tombstones are never deleted, because outside links still point at them, and never listed on Home.

Diátaxis's fourth mode, the learning-by-doing lesson, isn't used here. Readers arrive with a goal: build the code, run the tests, understand a piece of the design. If the wiki ever sets out to teach the codebase from nothing, that's a tutorial, and this page gets a section for it first.

Diátaxis's compass, applied to a paragraph or to a whole page:

Then one more question, which sits outside the compass: is it built? Built means committed to the repository, on bootstrap or main. If not, it's a Design page wherever the compass points.

If a draft resists the compass, it's almost always two pages. Split it. A built system ends up as a fixed set of pages, described under A system's pages.

Seven values, borrowed from the RFD process. The colour is the badge colour at the top of the page.

Guides, reference, explanation and index pages are only ever committed or superseded: they describe reality, so they're either current or replaced. A stale one is a bug to fix, not a state to record. Design pages may carry any of the seven.

Every page opens with one row of badges, then a blank line, then the opening paragraph:

![reference, committed](https://img.shields.io/badge/reference-committed-2ea44f) ![verified 2026-10-15](https://img.shields.io/badge/verified-2026--10--15-6e7781) [![bootstrap 94b4127](https://img.shields.io/badge/bootstrap-94b4127-6e7781)](https://github.com/NexusTomorrow/server/commit/94b4127)

Grey is for facts; only the status badge carries colour, so the eye lands on trust first.

Scope goes in the opening paragraph: one sentence on what the page covers and what's out, whenever the title doesn't make it obvious. Design pages always state it.

Supersession takes a banner directly under the opening paragraph, on both pages, as a NOTE alert that opens with a bold sentence:

> [!NOTE]
> **Read this page for direction.** [Page title](Page-file-name) describes what's built today.

A rename needs only the tombstone.

Every factual claim on this wiki is checkable, and the badges say how to check it.

• Numbers come from the source: the code in the repository, a test run, or a run on a local server. Never from a note, and never from memory of a note.
• When you can't verify a claim, keep it and label it: "read from the code, not run", "unverified". A labelled guess is useful. An unlabelled one is a trap.
• Re-badge a page whenever you touch what it describes. Treat a verified date older than six months as unverified until someone checks again.
• Design pages carry a Verification status section on top of the badges: which claims were measured, which were reasoned, and which are still open.

Where a thing goes, in the order the questions should be asked.

Pull requests track work. The wiki tracks understanding. A page links to the pull request that changed it with a live state badge, and never writes the state out by hand, because that copy goes stale.

The server is built as the systems listed on Server core design, and each one collects the same set of pages over its life. They're named after the system, so a system's pages sit together in the page list.

None of them restates another. Once the hub and its references exist, the design page moves to committed or superseded as Shipping a design says, and the systems table on Server core design points at the hub.

Where the code keeps an enumerable thing as a registry, such as its messages, runtime settings, commands, permissions or events, the reference page for it is generated from the built code by a tool in the repository, and committed here under the ref badge of the commit it was generated from.

• Never edit a generated page by hand. Change the code or its documentation comments, and generate it again.
• No hand-written table copies a registry. Link to the generated page. A second copy starts going stale on its first commit.
• A generated page opens with a NOTE saying it's generated and from what, and carries the same badges as any reference page.

• Changelogs, session notes, scratch files and tool output. If a page would be read once and never again, it isn't a wiki page.
• Credentials, server addresses, and personal details: real names, email addresses, machine names, local paths. Examples use placeholders (<client folder>) and obviously made-up characters.
• The client's own material, and anything showing how it was read. Facts about the client says where the line is.

The server has to agree with a client it can't change, so much of this wiki is facts about that client: what each message is for, what each field means (its units, its range, its set of values, which table an id indexes), the order the client expects things in, and how it behaves. A fact about the client is stated as a fact, the same way as a fact about our own code: "every in-game message carries a routing tag". Naming a client table or message is fine, and how sure we are of a fact goes in the badges and the Verification status section.

What stays off the wiki is the client itself and how it was read:

• addresses, decompiled code, disassembly, and the names or output of any tool used to read it;
• the client's own strings: its interface text, its script text and the names of its script events;
• dumps of its game tables, and long excerpts of anything it ships;
• how a fact was found. Say what's true, never the method.

Required sections per kind, grouped into chapters as the house style describes. Add more freely; don't drop these.

1. Pick the kind with the compass, then ask whether it's built.
2. Pick the status.
3. Write the header badges first, including the ref you're about to verify against.
4. Follow the skeleton for that kind.
5. Add it to Home under its kind with a one-line hook, and to the sidebar.

When the code lands, the truth moves off the design page and onto Reference and Explanation pages. Then either the design still describes what shipped, so mark it committed and point it at the reference set, or it drifted, so mark it superseded by the pages that now describe reality.

1. Add a banner to the old page and set its status to superseded.
2. Add the matching banner to the new page.
3. On a rename, reduce the old page to a one-sentence tombstone pointing at the new name, and take it off Home. Don't delete it.

When a change touches something a page describes, re-badge that page in the same piece of work. Wiki edits aren't a separate task from the work; they're part of it.

A page is due for a check when any path in its "Where the code lives" table changed since the commit its ref badge names:

git diff --name-only <badge commit>..origin/bootstrap -- <paths from the table>

Empty output means the code it describes hasn't moved, so a re-verify touches only the pages that print something.

Home lists every live page exactly once, each with a one-line hook. While the wiki is small it groups pages by kind. Once it passes about twenty pages it groups them by area instead, a system or a reader's concern such as hosting, with each page's kind beside it, because readers come looking for a system rather than a kind of page. Tombstones aren't listed. A page that isn't on Home doesn't exist as far as a reader is concerned, so adding the link is part of creating the page. The sidebar carries the same list.

The same format as the repository's own history: an imperative headline with no full stop, 72 characters or fewer, then a blank line before any further points.

Add a page on the server core design
Split the code standard into an explanation and the contributing rules
Re-verify the repository layout against bootstrap

One logical change per commit. Pull before you write, because more than one of us edits this wiki.

1. A badge row on top: kind and status, verified date, and a linked ref to a pushed commit.
2. Exactly one kind: no reference tables inside a guide, no instructions inside reference.
3. Chapters: a few H2s with H3s under them. No H1, no H4, sentence-case headings, no numbered headings.
4. Every number came from the source the badges name.
5. Every path, identifier and command is backticked, and paths are repo-relative.
6. No em dashes, and Canadian spelling in prose.
7. Internal links use page names, external links are real URLs, nothing is a bare URL, and pull requests carry live state badges.
8. A "Where the code lives" table on every page with a ref badge.
9. Diagrams top-down and narrow enough to clear the viewer's controls.
10. Nothing from the "doesn't belong here" list.
11. Linked from Home and the sidebar under its kind.
12. If it replaces or is replaced by another page, both directions are stated.

• Diátaxis, Daniele Procida. The four modes, the compass, and the incremental way of working.
• Oxide RFD 1: Requests for Discussion. The state ladder, and the argument for stamping authority on a document.
• MADR and Michael Nygard's architecture decision records. Context, decision and consequences, and the rule that a decision is superseded rather than edited away.