Documentation standards - rebaserHEAD/NexusForever 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 exists on stable, and thinking about what we intend to build. They need different rules, so 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.

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 it locally", "Verifying a feature".
• Steps go in the order the reader performs them, including the waiting.
• Handle real conditions with conditional imperatives: "If the client opens the launcher, check the file times in Patch\."
• 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 ("keep the Debug build while you work"), 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.
• Every reference page ends with a "Where the code lives" table: piece and path, paths in backticks and repo-relative.
• 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.
• Title it after the system plus "Design". Roadmap is the one exception: it's the design for what comes next as a whole.
• 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: run a server, add a feature, check a change. The closest thing, Running it locally, is a guide. 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 on stable? 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 shipped feature usually ends up as an Explanation hub carrying the why, the vocabulary and how the pieces hook together, plus one Reference page per moving part, plus the Design page it grew out of if it had one. None of them restates another. Galactic Archive and Galactic Archive messages and storage are the pattern.

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:

![guide, committed](https://img.shields.io/badge/guide-committed-2ea44f) ![verified 2026-10-14](https://img.shields.io/badge/verified-2026--10--14-6e7781) [![stable a4e75b18](https://img.shields.io/badge/stable-a4e75b18-6e7781)](https://github.com/rebaserHEAD/NexusForever/commit/a4e75b18)

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 on `stable` 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 on stable, the game tables, 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.

• 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: dumps of its game tables, long excerpts of its scripts, and anything showing how its code was read, such as addresses or decompiled code. A fact learned from the client is stated as a fact ("the article id is 14 bits"). Naming a client script or table is fine.

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 on stable.
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 on stable, 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.

Home lists every live page exactly once, grouped by kind, each with a one-line hook. 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.

Past-tense sentences with a full stop, the same as upstream's own history:

Added a page on account entitlements.
Split the web console page into a guide and a reference.
Re-verified the archive pages against stable.

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.
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, if it's a reference or explanation page.
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.