Documentation standards house style - NexusTomorrow/server GitHub Wiki

How words and markup look on this wiki. Which kind of page to write, and how to mark how far it can be trusted, is on Documentation standards.

The file name is the page title, with hyphens for spaces. Use sentence case: capitalize the first word and proper nouns only, and keep identifiers as the code spells them: Running-the-tests, Server-core-design.

• ASCII only, and never a colon. A colon can't exist in a Windows file name, so one page named with it makes the whole wiki impossible to clone on Windows.
• A subpage carries its parent as a prefix: Documentation-standards-house-style.
• No dates, no numbers, and no underscores outside _Sidebar.

The wiki draws a rule under every H2 and none under an H3, so the two levels read as chapters and steps. Use both.

• Group a page into a few H2 chapters with H3 sections inside them. A page with more than about six H2s in a row reads flat: nothing tells the eye which sections belong together. Chapter names like "Before you start", "Run" and "Troubleshooting" work for guides; "How it works" and "Coverage" for explanation.
• No H1. The wiki already renders the file name as the title.
• Never H4. If you need one, split the page.
• Sentence case: "Where the code lives", not "Where The Code Lives".
• No numbered headings; ordered procedures use a numbered list under a heading.
• A heading that needs a separator uses a colon, never a dash.

One to three sentences between the badges and the first H2. It says what the page covers, what's out if that isn't obvious, and who it's for. Never a heading called "Introduction" or "Overview".

Use GitHub's alerts, which render as coloured boxes with an icon. Four kinds:

> [!WARNING]
> Keep extracted tables and maps outside the repository.

Roughly one per chapter at most. If a section needs three, it's under-written, and the content belongs in prose or a table. Don't use [!CAUTION]; WARNING covers it.

The default shape for three or more parallel items.

• Always a header row, |---| separators, no alignment colons.
• Cells are fragments, not paragraphs.
• Bold the key column when the table is a lookup and the key is what the reader scans for.

• Keys go in <kbd>: Ctrl+C, Enter.
• A list item or paragraph that makes a rule leads with it in bold, then explains: "Nothing is committed to main directly. It moves only when we merge into it."

• Backtick every path, type, member, opcode, config key, command and table name.
• Paths are repo-relative from the repository root: Source/NexusTomorrow.Cryptography/Srp6Provider.cs.
• Fenced blocks get a language tag. Keep them short: a fenced block is an illustration, not an appendix.
• Never paste a whole file. Cite the path and quote the lines that matter.

• Internal links use the page file name, with no extension and no URL: [Running the tests](Running-the-tests).
• Link text is the page's real title or a natural noun phrase. Never "here", never "this page", never a bare URL.
• Link on the first mention in a section, not every mention.
• External links use the full https URL, and only for sources, repositories, pull requests and specifications.

Link a pull request with a live state badge, so its state stays true without an edit:

[![#1](https://img.shields.io/github/pulls/detail/state/NexusTomorrow/server/1?label=%231)](https://github.com/NexusTomorrow/server/pull/1)

In running prose, a plain link ([#1](...)) is fine.

• A space between value and unit: 2.3 GB, 25 ms.
• Thousands separators from four digits up: 1,028.
• Bit patterns in hex with a 0x prefix, in backticks: 0x087F.
• A message is named by its opcode, 0x087F, and described in words where what it does is known. The code names a message after its opcode (Server087F) until it's been checked against the client, and only then gives it the client's own name; once it has one, put it beside the opcode. The client fixes the opcode, so the opcode is what a link or a search should rely on.
• Dates in ISO form, YYYY-MM-DD, everywhere. Never "last Tuesday".

• Canadian spelling in prose: behaviour, colour, centre, licence as a noun. Identifiers stay exactly as the code spells them. The code standard moves identifiers to American spelling, so older code and newer code can differ for a while; quote whichever the code says.
• No em dashes. Use a comma, a colon, parentheses or two sentences, in headings too.
• Short paragraphs, two to four sentences. A paragraph that runs past six lines is hiding a list.
• Guides use "you". Reference is impersonal. Explanation and Design use "we" for choices we made.
• Direct verbs, and the mechanism rather than the adjective: "the map drains its message queue at the start of every tick" beats "the map is responsive".
• No marketing, no filler openers, no decorative emoji.

Mermaid renders on the wiki. Use a diagram when the topology is genuinely a graph and prose would need three paragraphs to say it.

• Top-down by default (flowchart TD). The wiki overlays its zoom and pan controls on the right edge of every diagram, so a wide left-to-right chart ends up underneath them.
• At most about three nodes wide, so the diagram sits in the middle of the page, clear of the controls.
• Keep node and edge labels to about four words. A diagram that needs sentences in its boxes is a table.
• One diagram per page, unless the page is about a pipeline. sequenceDiagram for a protocol exchange.
• Use a dotted edge (-.->) for a path that leaves the system.

Commit them under images/ and reference them relatively, named <page-file-name>-<subject>.png. A screenshot needs a one-line caption saying what to look at. Leave out the client's own art and interface for now: they're NCSOFT's material, and whether to use them here is still open.