Evaluate Engineering Documentation Platform

[linear]

Summary

We need to establish a centralized platform for internal engineering documentation. Requirements include:

• Documentation authored and maintained by engineers
• Content stored and versioned in GitHub
• Documentation changes reviewed through the normal PR process
• Access available to all company employees with GitHub access
• Low operational overhead
• Potential future support for external-facing documentation if needed

Goals

• Define the preferred documentation platform and hosting model
• Establish a scalable documentation structure for architecture, runbooks, operational procedures, ADRs, and engineering standards
• Minimize maintenance and infrastructure requirements
• Ensure documentation remains version-controlled and reviewable

Options Under Consideration

Option A: GitHub Pages Only

Store documentation as Markdown within a GitHub repository and publish directly via GitHub Pages.

Pros:

• Simple setup
• Minimal tooling
• Low maintenance

Cons:

• Limited navigation and documentation experience
• Basic search capabilities
• Less scalable as documentation volume grows

Option B: Docusaurus + GitHub Pages

Use Docusaurus as a static site generator while continuing to store all documentation as Markdown in GitHub.

In this model:

Engineer writes/updates Markdown
        ↓
Pushes PR to GitHub repo
        ↓
PR review/merge to main
        ↓
GitHub Action runs Docusaurus build
        ↓
Docusaurus outputs static HTML/CSS/JS
        ↓
GitHub Pages serves that static output

Repository structure could resemble:

engineering-docs/
├── docs/
│   ├── intro.md
│   ├── architecture/
│   │   └── ai-platform.md
│   └── runbooks/
│       └── deploy.md
├── sidebars.js
├── docusaurus.config.js
├── package.json
└── .github/
    └── workflows/
        └── deploy.yml

Engineers primarily contribute documentation within:

docs/**/*.md

Docusaurus provides:

• Structured sidebar navigation
• Search
• Versioned documentation
• Dark mode
• Table of contents generation
• Cross-document linking
• Better overall documentation UX

GitHub Pages serves as the hosting layer while GitHub Actions handles build and deployment.

Initial Proposed Direction

Current recommendation is to evaluate Docusaurus hosted via GitHub Pages as the default solution.

This approach provides:

• Git-based documentation workflows
• PR-based review process
• Low operational overhead
• Improved documentation experience compared to raw Markdown publishing
• No requirement to manage custom hosting infrastructure