Why we're doubling down on docs

Developers don't love writing docs, but teams love what great docs do: faster onboarding, fewer “how does this work?” pings, fewer regressions, and quicker integration with partners. A clear framework-what to write, where to put it, and how to keep it current-turns documentation from a chore into compounding leverage. Community best practices (like the “four kinds of documentation”: tutorials, how-to guides, reference, and explanations) help us keep content purposeful instead of bloated. [1]

Our core approach: Confluence as the “single source of truth”

We already use Atlassian Confluence as our live, internal knowledge base, and we're leaning into it with a few disciplined patterns:

Spaces-by-domain + page templates. Each major area (gameplay, backend, economy, art, platform) owns a Space with consistent templates-architecture overview, runbooks, decision records (ADRs), and change logs.
Tight permissions. We keep “write” small and “read” broad-spaces are open by default, but sensitive pages (e.g., partner terms, certain endpoint notes) are restricted at the page level to specific groups. Confluence supports site-, space-, and page-level permissions; restrictions can limit view and/or edit access. [2][3][4]
Security hygiene. Credentials never live in pages. Where we must store membership credential notes (e.g., renewal windows, contacts), we reference our secret manager and restrict the Confluence page to a minimal group, avoiding raw secrets entirely. (Confluence helps with fine-grained page restrictions, but we still treat it as a place for pointers, not secrets.) [3][4]

Why Confluence works for us: real-time editing, hierarchical organization, and permissioning that scales with the team-without feeling ad-hoc or “wiki-wild.” [2][3]

Docs-as-code for long-lived guides (free + dev-friendly)

Not everything belongs in Confluence. For stable, versioned guides (SDK tutorials, modding docs, advanced troubleshooting), we prefer docs-as-code stacks that live in Git with CI:

Docusaurus - Markdown, versioning, i18n, search, and easy static deploys (Vercel/Netlify/GitHub Pages). Great for public-facing docs and developer portals. [9][10][11][12]
MkDocs - Super fast, Markdown-first, simple YAML config; live dev server and one-command deploys. Excellent free option for internal or public docs. [13][14][15][16]
Sphinx - Powerful cross-referencing, multiple output formats (HTML/PDF), auto-API references; ideal when you need deep structure or Python ecosystems. [17][18][19]
Read the Docs - Builds & hosts docs from your repo; free for open source with versioning, PR previews, and integrated search (paid plans for private docs). [20][21]

When we choose which:

Rapid, branded dev portal → Docusaurus. [9][10]
Lightweight internal handbooks → MkDocs. [13]
Heavily cross-referenced, API-heavy, or PDF deliverables → Sphinx. [17][18]
OSS library docs → Read the Docs (plus Sphinx/MkDocs under the hood). [20][21]

Editorial discipline: how we keep docs useful (and maintainable)

Follow a content model. Every page declares its type (Tutorial / How-to / Reference / Explanation) up top; this keeps scope sharp and avoids “Franken-pages.” [1]
Adopt a house style. Short sentences, consistent terminology, inclusive language, and linkable anchors. A style guide saves time and improves trust. We borrow from community style-guide patterns and adapt to our voice. [22][23][24]
Docs gates in CI. For APIs, builds fail if the OpenAPI file is invalid. For doc sites, broken links or missing front-matter block merges.
Change ownership. Every Space and every doc set lists an owner and review cadence (quarterly review for “reference,” per-release review for “tutorials”).
“What changed?” first. For each feature milestone (e.g., interactive NPCs), we publish a short changelog entry that links to deeper docs-keeping readers oriented.

Tooling stack we're standardizing (and why)

Internal knowledge & decision history:

Confluence with spaces, templates, and page-level restrictions; decision records (ADRs) and runbooks live here. [2][3][4]

Public/partner docs & API references:

OpenAPI source of truth, rendered via Swagger UI (interactive), checked in CI. [5][6][7][8]
Docusaurus for the public developer portal (versioned tutorials, guides). [9][10][11]

Lightweight internal handbooks:

MkDocs repos for each discipline (Engineering Handbook, Live-Ops Playbook), with auto-deploys on merge. [13][16]

Deep, reference-heavy docs (as needed):

Sphinx for cross-referenced internals and PDFs; hosted privately or on Read the Docs for OSS assets. [17][18][20]

Optional hosted platform:

GitBook for teams that want a polished hosted experience with branching, reviews, and a Markdown editor. (We treat this as a complement-not a replacement-for OpenAPI and docs-as-code.) [25][26]

Practical tips we're using right now

Make it effortless to contribute. Templates for new pages (Confluence) and new docs (Docusaurus/MkDocs) remove friction. [9][13]
Document intent and interfaces. For our NPC interaction work, we capture: player stories (intent), state diagrams (flow), and the API contract (interface). The contract lives in OpenAPI and drives everything else. [5][7]
Keep secrets out of docs. Use Confluence only for process notes or access instructions, and rely on secret managers; enforce page-level restrictions for anything sensitive. [3][4]
Review little, review often. Short, frequent docs PRs beat end-of-sprint dumps.
Indexability matters. Our public docs ship with sitemaps, search, and clean URLs to help devs (and search engines) find answers fast. Docusaurus and Read the Docs both help here. [10][21]

References

Procida, D. The four kinds of documentation (tutorials, how-to, reference, explanation). Write the Docs. [1]
Atlassian. Manage Confluence site and space permissions. [2]
Atlassian Support. Manage permissions at the content (page) level. [3]
Atlassian. Permissions and restrictions (page/space controls). [4]
OpenAPI Initiative. What is OpenAPI? [5]
Swagger. Swagger UI — interactive API documentation. [6]
OpenAPI Initiative. Benefits of OpenAPI across the API lifecycle. [7]
Swagger. Documenting APIs with OpenAPI & Swagger tools. [8]
Docusaurus Docs. Introduction to Docusaurus. [9]
Docusaurus. Build optimized documentation sites; versioning/i18n/search. [10]
Docusaurus Docs. Create a doc (URLs, structure) & deployment options. [11][12]
Docusaurus Docs. Deployment guide (Vercel, GitHub Pages, Netlify, etc.). [12]
MkDocs. Project documentation with Markdown (fast, simple). [13]
MkDocs User Guide. Writing your docs (layout, Markdown). [14]
MkDocs User Guide. Configuration basics (YAML). [15]
MkDocs User Guide. Deploying your docs (gh-deploy). [16]
Sphinx Docs. Create intelligent, highly structured documentation. [17]
Sphinx Docs. Getting started & auto-generated API references. [18][19]
Sphinx Docs. Tutorial: build your first project (HTML/PDF outputs). [19]
Read the Docs. Full-featured documentation build & hosting platform. [20]
Read the Docs Pricing. Free for public open source, paid for private/SSO. [21]
Write the Docs. Software documentation guide (best practices). [22]
Write the Docs. Style guides: maintain consistent tone & terminology. [23]
Write the Docs. Documentation principles (DRY/KISS applied to docs). [24]
GitBook. Documentation platform (Markdown editor, reviews, integrations). [25][26]