Skip to content

Writing Documentation

This guide explains how documentation in this site is structured, written, and maintained. Following these conventions keeps pages consistent, readable, and easy to update — including by AI-assisted tools.

Scope

This guide covers:

  • how to add a new page
  • how different page types are structured
  • how to update existing pages
  • naming and formatting rules

It does not cover backend code conventions. Those live in Docs/Architecture/.

Adding a New Page

  1. Create a .md file in the appropriate folder under docs/.
  2. Add an entry to the nav section in mkdocs.yml.
  3. Follow the structure rules below.

Navigation labels should be short, clear, and match the page heading.

Before creating a page, decide which section it belongs in:

  • features/ for implemented or current gameplay behavior
  • ideas/ for rough design exploration and open questions
  • pitch/ for concepts prepared for community feedback or voting

Page Types

This documentation site uses three main page types.

Features

Feature pages describe gameplay that is already implemented or otherwise treated as current game behavior.

Use features/ when the goal is to explain what the game currently does.

Ideas

Idea pages collect design exploration.

Use ideas/ when the goal is to capture:

  • rough concepts
  • multiple competing options
  • open tradeoffs
  • unresolved design questions

Idea pages should not read like finished product documentation.

Pitch

Pitch pages present selected ideas in a clearer, more curated form for community discussion.

Use pitch/ when the goal is to explain a proposed direction and invite feedback or interest.

Pitch pages can be more opinionated than idea pages, but they should still make it clear that the content is proposed rather than final.

Feature Page Structure

All feature pages use the same section template. This makes pages predictable and easier to scan, compare, and update programmatically.

Feature pages are written for players, not developers. They describe what exists in the game and what players can do — not why a feature was built, what problem it solves, or what value it provides. That framing belongs in design documents, not in documentation that players read.

Template

# Feature Name

Brief one- or two-sentence summary of what this feature is.

---

[One or more content sections describing the feature — what types exist, how it is organised, how it works. Use descriptive headings relevant to the subject matter.]

---

## Rules

The governing rules for this feature. Be specific. Avoid vague statements.
Write as facts about the game world, not instructions to the player.

---

## Player Actions

What actions the player can take within this feature.
Use a list.

---

## Constraints

Hard limits or design boundaries that apply to this feature.

The content sections between the opening summary and ## Rules are flexible. Use headings that match the subject matter — for example, ## Types, ## Categories, or a subject-specific heading like ## Stellar Object Types. Add as many content sections as needed to fully describe the feature.

Rules for Using the Template

  • Write for a player reading documentation about the game, not for a developer understanding a design decision.
  • Do not include a "Purpose" section, a "Player Value" section, or any section that explains why the feature exists or what problem it was designed to solve.
  • Keep each section focused. Do not mix rules with player actions.
  • Use lists where the content is enumerable.
  • Use plain declarative sentences, not marketing language.
  • Every section must contain confirmed facts. Feature pages are not drafts — nothing may be left undefined or marked as pending.
  • Feature pages must not reference anything outside of docs/features/.

Updating Existing Pages

When updating a page:

  • Edit only the section that changed.
  • Do not remove the section heading, even if the section is temporarily empty.
  • Keep the section order the same as the template.

This consistency is important for automated document processing.

Idea Page Structure

Idea pages are more exploratory than feature pages.

Suggested structure:

# Idea Name

Short summary of the concept.

---

## Goal

What this idea is trying to solve or improve.

---

## Core Problem

What design tension or gap led to this idea.

---

## Working Directions

Promising approaches, candidate models, or alternative solutions.

---

## Open Questions

Important unresolved questions that still need discussion.

Rules for idea pages:

  • make uncertainty explicit
  • include options where useful
  • avoid writing speculative content as if it were final behavior
  • preserve important open questions instead of forcing fake certainty

Pitch Page Structure

Pitch pages are more polished than idea pages, but still describe proposed content.

Suggested structure:

# Pitch Name

Short summary of the proposal.

---

## What This Proposal Is

High-level explanation of the proposed feature or change.

---

## Why It Matters

Why this proposal would improve the game or player experience.

---

## Key Points

The main pillars of the proposal.

---

## Questions For Feedback

Specific points the community can react to.

Rules for pitch pages:

  • make the proposal easy to scan
  • focus on player-facing value
  • be clear that the content is proposed, not guaranteed
  • leave room for feedback and disagreement

Writing Style

  • Use plain, direct language.
  • Write in present tense where possible.
  • Prefer short sentences and short paragraphs.
  • Use concrete terms from the Glossary rather than informal synonyms.
  • Do not add filler phrases like "it is worth noting" or "as mentioned above".

Formatting Rules

  • Use # for the page title only.
  • Use ## for the main sections defined in the template.
  • Use ### for subsections when truly needed.
  • Separate sections with a horizontal rule (---).
  • Use fenced code blocks with language tags for any code or config snippets.
  • Use inline code (backticks) for identifiers, file names, and configuration keys.

File Naming

  • Use lowercase with hyphens: universe-foundation.md, not UniverseFoundation.md.
  • Use descriptive names that match the page title.

Running the Site Locally

See the repository README or the setup instructions in Docs/User/ for install and run commands.