Repository navigation
Style Guide
Every page in this wiki follows the rules below. They exist so readers find what they need, scan it fast, and leave knowing what to do. Read this first before editing a page.
Every page opens with four things, no exceptions:
- What this page is — one sentence. A tutorial? A how-to? A reference? State it.
- Who it's for — one sentence. Player. GM. Builder.
- What you need before starting — prerequisites. Software installed, a Novel created, a ruleset converted.
- What you'll walk away with — the outcome. A running server. A character sheet. A built adventure.
Source: MediaWiki Documentation Style Guide (audience-first design). This gives every reader a fast path to decide "is this page for me?" without reading the whole thing.
Every page belongs to exactly one category. Never mix two in the same page. If you find yourself drifting, split the page.
| Type | Purpose | Shape | Example |
|---|---|---|---|
| Tutorial | Get a beginner from zero to working result | Step-by-step, numbered, concrete. Every step produces visible output. | Getting Started — install, configure, first session. |
| How-to | Solve a specific problem | Starts with a goal. Shows the path. No theory. | "How to generate an adventure from a premise." |
| Reference | Technical facts for lookup | Tables, field lists, dry and exhaustive. No narrative. | Adventure module format spec. Lorebook field reference. |
| Explanation | Background, design decisions, "why" | Prose. Context-heavy. Connects dots. | Why Holonovel uses badges instead of logins. State model overview. |
Source: Divio/Diátaxis documentation system (diataxis.fr). The separation exists because a reader who wants a tutorial skips reference tables, and a reader who wants a field spec doesn't want a story. Mixing them frustrates both.
Import the README's voice into every page. The README sets the standard — punchy, direct, benefit-first.
You are the subject. Address the reader as "you." Never "the user" or "one." Imperative mood for procedures: "Create a Novel." Not "The user must create a Novel."
Demo quotes, never tool names. Show what the reader says — never what function they call:
"Look up Fireball." "Attack the ogre with my longsword."
Not: lookup_spell("fireball") or roll_weapon_attack.
Source: README design conventions (README.md, HTML comment lines 1–171). Demo quotes let readers recognize their own voice. Tool names are for the AI, not the human.
Benefit-first. Open every section with what the reader gains, not what the system does.
Do: "Your characters are permanent. The roster survives every campaign." Don't: "The roster stores character data across sessions."
Competitive proof. One sentence per feature contrasting against what readers are used to.
"Every other AI GM trusts a prompt to keep secrets between badges; Holonovel enforces badge boundaries server-side."
Source: README.md §2 feature blurbs — four-beat cadence (benefit hook, mechanics, competitive proof, closer).
Be friendly, not academic. Write like you're explaining to someone at the table.
Do: "Start by creating a character." Don't: "The user must first initiate the character creation workflow."
Source: MediaWiki Documentation Style Guide (voice and tone table).
No "easy" or "simple." What's easy for you may be hard for someone else. Describe the steps; let the reader decide the difficulty.
Source: MediaWiki Documentation Style Guide (free of frustration).
Reference hierarchy. When a style question isn't answered here, consult in this order:
- Project-specific guidelines (README, AGENTS.md)
- This style guide
- Merriam-Webster for spelling, Chicago Manual of Style for non-technical usage, Microsoft Writing Style Guide for technical usage.
Source: Google Developer Documentation Style Guide (reference hierarchy).
Break the rules when it serves the reader. This guide contains guidelines, not rules. If following a guideline produces worse documentation for your specific page, depart from it — and be consistent within that page.
Source: Google Developer Documentation Style Guide ("Break the rules" clause, citing Orwell's "Politics and the English Language").
Readers scan. They don't read. Write so they find their answer in under ten seconds.
One idea per paragraph. If a paragraph contains two ideas, split it.
Short sentences. If a sentence runs past 25 words, break it. Compound sentences with three or more clauses don't survive scanning.
Define unfamiliar terms on first use. "MCP (Model Context Protocol)." Never assume the reader knows an acronym or domain term. For a term the reader should already know — "badge" or "Novel" — no definition is needed.
Use positive constructions. Tell the reader what to do, not what not to do. "Keep the sidebar under 20 links" is clearer than "Don't exceed 20 links in the sidebar."
Use active voice. "You create a Novel" lands faster than "A Novel is created." Passive voice is for when the actor doesn't matter.
Avoid colloquialisms, jokes, and idioms. "A piece of cake," "barking up the wrong tree," and "easy peasy" don't translate. Readers working in their second language shouldn't need a cultural decoder.
Source: MediaWiki Documentation Style Guide (voice and tone table); plainlanguage.gov (active voice and positive constructions).
Holonovel serves readers of all backgrounds, genders, and native languages. Every page respects that.
No gendered pronouns for unknown people. "When the player joins, they select a Novel." Not "he selects." If the sentence can't work with "they," restructure it.
No ableist language or violent metaphor. "Unusual" or "unexpected," not "crazy" or "insane." "Terminate" or "stop," not "kill."
No terms that carry exclusionary history. "Allowlist"/"denylist," not "whitelist"/"blacklist." "Primary"/"secondary," not "master"/"slave."
Example names are diverse and non-stereotyped. Use a mix of names from different cultures. "Aria," "Idris," "Yuki," "Fatima" — not five male Anglo names.
Source: MediaWiki inclusive language guidelines; GitHub Docs style guide (inclusive language section); Write the Docs reducing-bias guide.
Each page covers one thing well. If a page covers three things, it's really three pages.
Rules of thumb:
- If a procedure runs more than 5 steps, consider splitting.
- If a heading grows past 300 words, it's a candidate for its own page.
- If you use "and" in a page title, you probably need two pages.
Docs are the single source of truth. If the answer to a question exists in a wiki page, link to it — don't rephrase it inline. If the answer doesn't exist anywhere, add a page for it. Avoid the same information living in two places.
Source: opensource.com, "3 tips for effectively using wikis for documentation." Topic-based writing prevents wiki pages from becoming online versions of thick manuals. Source: GitLab Docs style guide (docs-first methodology).
Sentence case. "Creating a character," not "Creating A Character" or "Creating a Character." No links inside headings (breaks mobile).
Source: MediaWiki Documentation Style Guide (titles and headings).
No CamelCase in titles. "Getting Started," not "GettingStarted."
Source: opensource.com (camelCase is visually jarring and signals "wiki software, 2004").
Every page follows a strict nesting discipline.
Start at H2 (##). The page title is the H1. Body headings begin at H2.
Never skip a level. H2 → H3 → H4. An H4 without a preceding H3 is illegal.
Never repeat a heading at the same level. Two H2s with the same text confuse in-page anchors and search.
Each heading must have content between it and its subheading. An H2 immediately followed by an H3 is a structure error.
Capped at H5. If you need six levels of heading, split the page.
Source: GitHub Docs style guide (header hierarchy section); GitLab Docs style guide (heading rules).
Emphasis is a scarce resource. Overusing it defeats it.
Bold at most five contiguous words. A bold paragraph is unreadable.
Never use bold as the sole carrier of meaning. If removing bold from a sentence changes its meaning, rewrite the sentence.
Italics for terms, not emphasis. Italicize a term on first use if it needs definition. Don't use italics for stress — the sentence should carry its own weight.
No bold in headings. If a heading needs emphasis, the heading itself is too weak.
Source: GitHub Docs style guide (emphasis section); GitLab Docs style guide (bold reserved for UI labels).
Use fenced code blocks with language tags:
```sh
cd holonovel && npm install && npm run start
```
Keep example lines under ~60 characters. Longer lines wrap on mobile and break in narrow viewports.
No $ prefix on commands. The prompt character breaks copy-paste.
ALL-CAPS for placeholders. "npx holonovel init YOUR-PROJECT" — the reader
replaces YOUR-PROJECT with their own name.
Explain before the block. The sentence before a code block tells the reader what the code does. The code block itself has no inline comments as explanation.
For reference data and comparisons. Never for page layout.
Source: MediaWiki Documentation Style Guide (mobile-friendly formatting).
Define on first use: "MCP (Model Context Protocol)."
Every image needs alt text. 40–150 characters describing what the image shows. "Screenshot of the character creation dialog with the 'Roll stats' button highlighted." Never start alt text with "Image of" or "Screenshot of" — the image type is implied.
Images illustrate, they don't instruct. A reader who can't see the image must still complete the task.
Never use real values in examples. No real API keys, tokens, email addresses, or
passwords. Use example.com for domains, and prescribed placeholder values like
YOUR-TOKEN.
Source: GitHub Docs style guide (code examples, images, fake data); GitLab Docs style guide (fake data conventions).
Not all readers speak English as a first language. Every page is written so it survives machine translation.
Avoid hidden subjects. "There is a button" and "It is required" lose their referent in translation. Name the thing: "The save button sits in the top right."
Avoid ambiguous pronouns. If "it" could refer to two different nouns in the same sentence, the translator will guess wrong. Repeat the noun.
No -ing words where the subject is implied. "After installing" doesn't say who
installed. "After you install" does.
No Latin abbreviations. "For example," not "e.g." "That is," not "i.e." Latin abbreviations don't exist in many languages.
Allow for text expansion. English is compact. Translations into German, French, or Spanish can expand 30% or more. Short English sentences leave room.
Source: GitLab Docs style guide (writing for localization section); MediaWiki translation guidelines.
Use clear headings, bullet points, and code blocks. Blocks of prose go last. Readers scan for their answer; give them landmarks.
Source: Pullflow, "The Documentation Strategy Behind Every Successful Open Source Project."
Every page carries a _Last updated:_ footer with the date.
Source: Pullflow (outdated docs are worse than no docs; a date lets readers assess freshness).
Links are commitments. Every broken or misdirected link costs trust.
Use descriptive link text. The link text should tell the reader where they're going. "See the character creation guide" — not "click here" or "read more."
Don't repeat links in the same page. A link to the same target appears at most once outside the See Also section.
No links inside headings. Links in headings break mobile rendering and confuse screen readers.
Place optional links at the bottom. If a link is nice-to-know but not essential to the task, it goes in the See Also section, not inline.
Verify links before publishing. Click every link on the page. A stale link is worse than no link.
Source: GitHub Docs style guide (links section); MediaWiki Documentation Style Guide (mobile-friendly headings).
The sidebar (_Sidebar.md) is the primary navigation. It groups pages by audience.
Every page appears there.
See Also section. Every page ends with links to 2–3 related pages. This creates a mesh that survives the sidebar being hidden.
Source: opensource.com (topic-based writing needs explicit navigation to avoid disjointed pages).
No orphan pages. Every page has at least one inbound link from another wiki page.
- Descriptive, not clever. "Building a Server," not "The Forge."
- Hyphens between words: "Getting-Started," "Game-Mastering," "Adventure-Modules."
- No file extensions in titles.
- No verb-first titles ("How to Create a Character" → "Character Creation" or "Creating a Character").
- Reference pages use noun form ("Adventure Module Format"). Tutorial/how-to pages use gerund form ("Building a Server").
Every page targets one primary audience. The preamble states it. Links to other audiences' pages go in "See Also," not inline.
| Audience | What they need | Page types |
|---|---|---|
| Player | "How do I play?" | Tutorial, How-to |
| Game Master | "How do I run the world?" | How-to, Reference |
| Builder | "How do I build a server?" | Tutorial, Reference |
Source: MediaWiki Documentation Style Guide (audience and content — writing for technical audiences).
Every page stands alone. A reader should understand it without opening the repository. But every claim cites its source — a spec section, a REQ number, or a README section — so a skeptical reader can verify.
Format: "per REQ-066" or "see spec §6.5" or "source: README.md §2."
Source: User requirement — self-contained pages with cited sources.
Stale documentation is worse than no documentation.
Every page carries a _Last updated:_ date. The date tells readers whether the
information is current. Update the date on every edit, even small ones.
Remove or mark outdated content. If a page refers to a feature that has changed, update it or add a warning banner. Never leave wrong information live.
Periodic review. Every six months, the maintainer who last edited a page reviews it for accuracy. Stale pages are flagged in the sidebar.
Dead link patrol. Broken links are fixed within one week of discovery.
Maintained by the project owner. The wiki is written and maintained by the project owner. Readers who find a problem can report it through the repository.
Source: Pullflow documentation strategy guide; MediaWiki Documentation Style Guide (review and maintenance); GitHub Docs best practices.
Before publishing a page, verify:
- Preamble declares type, audience, prerequisites, and outcome.
- Single Diátaxis type maintained throughout (no drift).
- Voice matches README: second person, demo quotes, benefit-first.
- No "easy," "simple," "just," or "obviously."
- Positive constructions used (tell what to do, not what not to do).
- Active voice throughout (passive only when actor doesn't matter).
- No colloquialisms, idioms, jokes, or culture-specific references.
- Inclusive language: no gendered pronouns for unknown people, no ableist terms, no exclusionary history terms.
- Abbreviations defined on first use.
- Headings use sentence case; H2–H5, no skipped levels, no duplicates.
- Bold ≤5 contiguous words, never sole carrier of meaning.
- Code blocks fenced with language tags, lines ≤~60 chars, no
$prompt. - All images have alt text (40–150 chars).
- All example values are fake (no real keys, tokens, or email addresses).
- No hidden subjects or ambiguous pronouns (survives translation).
- No Latin abbreviations (for example, that is) — spell them out.
- All links verified, no duplicates within page, no links in headings.
- Link text is descriptive ("see the character creation guide," not "click here").
- "See Also" section links 2–3 related pages.
- Source citations present for non-obvious claims (per REQ-XXX or see spec §X.Y).
-
_Last updated:_date in footer. - Page is scannable: headings, bullets, and code blocks before prose walls.
- Page targets one primary audience stated in preamble.
- Home — the page that sets the tone
- What Holonovel Is — explanation page following Diátaxis and topic-based design
Last updated: 2026-10-12.
Holonovel Wiki
Tutorials
For Players
For Game Masters
For Builders
Meta