DEVLOG-5: Docs as a Feature - How We’re Scaling Documentation

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)

1. Internal knowledge & decision history:

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

1. 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]

1. Lightweight internal handbooks:

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

1. 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]

1. 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

1. Procida, D. The four kinds of documentation (tutorials, how-to, reference, explanation). Write the Docs. [1]

2. Atlassian. Manage Confluence site and space permissions. [2]

3. Atlassian Support. Manage permissions at the content (page) level. [3]

4. Atlassian. Permissions and restrictions (page/space controls). [4]

5. OpenAPI Initiative. What is OpenAPI? [5]

6. Swagger. Swagger UI — interactive API documentation. [6]

7. OpenAPI Initiative. Benefits of OpenAPI across the API lifecycle. [7]

8. Swagger. Documenting APIs with OpenAPI & Swagger tools. [8]

9. Docusaurus Docs. Introduction to Docusaurus. [9]

10. Docusaurus. Build optimized documentation sites; versioning/i18n/search. [10]

11. Docusaurus Docs. Create a doc (URLs, structure) & deployment options. [11][12]

12. Docusaurus Docs. Deployment guide (Vercel, GitHub Pages, Netlify, etc.). [12]

13. MkDocs. Project documentation with Markdown (fast, simple). [13]

14. MkDocs User Guide. Writing your docs (layout, Markdown). [14]

15. MkDocs User Guide. Configuration basics (YAML). [15]

16. MkDocs User Guide. Deploying your docs (gh-deploy). [16]

17. Sphinx Docs. Create intelligent, highly structured documentation. [17]

18. Sphinx Docs. Getting started & auto-generated API references. [18][19]

19. Sphinx Docs. Tutorial: build your first project (HTML/PDF outputs). [19]

20. Read the Docs. Full-featured documentation build & hosting platform. [20]

21. Read the Docs Pricing. Free for public open source, paid for private/SSO. [21]

22. Write the Docs. Software documentation guide (best practices). [22]

23. Write the Docs. Style guides: maintain consistent tone & terminology. [23]

24. Write the Docs. Documentation principles (DRY/KISS applied to docs). [24]

25. GitBook. Documentation platform (Markdown editor, reviews, integrations). [25][26]