Docs-as-Code Primer

Docs-as-Code Primer

Commit activity for maintainer @snowballons — the kit is kept in the PR, like the docs it teaches.

Adopt the scaffold in one line

bash <(curl -fsSL https://raw.githubusercontent.com/snowballons/docs-as-code-primer/main/scaffold-init.sh)

Copies the scaffold/ copy set (docs/, CI workflow, PR template, AGENTS.md, .markdownlint.json) into the current repository. Nothing is overwritten by default — add --overwrite to replace existing files, --prefix <dir> for a monorepo, --with-llms-txt for llms.txt, and --dry-run to preview. Prefer working offline? Run bash scaffold-init.sh --kit-dir /path/to/docs-as-code-primer from a local clone instead.

After copying, follow FIRST_WEEK.md and set KIT_URL in docs/KIT.md. The manual path is documented in scaffold/README.DOCS.md.

Structure, phases, and templates for documentation that ships with your code.

Internal docs for engineers. User docs for customers. Shared truth in between.
Copy the kit. Follow the phases. Keep docs in the PR.

This is a primer + project structure kit — not an awesome list, not a hosted docs platform, not a full engineering handbook. It is a portable operating system for documentation.

Start here (pick one)

Canonical phase → folder map: appendix/phase-folder-map.md
After copy into a product repo: set KIT_URL in docs/KIT.md (ships with the scaffold).

flowchart TB
    primer["Docs-as-Code Primer\n(judgment + phases)"]

    templates["Templates\n(shape)"]
    scaffold["Project scaffold\ninternal / user / shared"]
    recipes["Recipes\n(publish)"]
    repo["Your real repo"]

    primer -->|informs| scaffold
    templates -->|shape| scaffold
    recipes -->|wire| scaffold
    scaffold -->|copy into| repo

What you get

1. Primer — what to write, when, for whom, and how to keep it alive (Phases 0–9 + two-audience rules).
2. Scaffold — a copy-paste docs/ tree: internal/, user/, shared/, plus starter CI and AGENTS.md.
3. Templates — ADR, runbook, charter, module spec, deprecation notice, and more.
4. Example — Acme Export Platform with filled samples.
5. Recipes — wire MkDocs, Docusaurus, or Mintlify later; structure first, site generator second.

Non-negotiable rules

1. Docs are code — Git, pull requests, CI checks, versioned with the product.
2. Two audiences, one repo — /docs/internal, /docs/user, /docs/shared.
3. Never leak internal content into user docs without deliberate curation.
4. Never maintain the same fact in two places without a reuse mechanism.
5. Definition of Done includes docs — update docs in the same change when behavior changes.
6. Diagrams as code by default — Mermaid for living engineering diagrams.

Phase map

Phases overlap. Phase 8 never ends. Use them as a mental model, not a bureaucracy.

Full phase → folder → template index: appendix/phase-folder-map.md.

Repo layout

docs-as-code-primer/
├── README.md                 ← you are here
├── FIRST_WEEK.md             ← adoption path after copy
├── LEARNING_PATH.md          ← ordered path through the primer
├── CONTRIBUTING.md
├── LICENSE
├── primer/                   ← teaching layer
├── scaffold/                 ← copy into your project
├── templates/                ← fill-in-the-blank artifacts
├── examples/                 ← one worked product
├── recipes/                  ← how to publish / wire tools
└── appendix/                 ← glossary, tooling map, phase→folder map

Scaffold tree view (copied into your project):

docs/                         ← copy scaffold/docs/ into your repo
├── internal/                 ← engineers, ops, compliance
│   ├── charter/              ← vision, scope, stakeholders, risks
│   ├── requirements/         ← user stories, functional, NFRs
│   ├── architecture/         ← context, container, C4 diagrams
│   ├── decisions/            ← ADRs (append-only)
│   ├── system-design/        ← services, APIs, DB schemas, security
│   ├── development/          ← how to build, test, deploy
│   └── operations/           ← runbooks, SLOs, monitoring, DR
├── user/                     ← customers, support
│   ├── getting-started/      ← quickstart, tutorial
│   ├── guides/               ← how-to, feature docs
│   └── api-reference/        ← generated or curated API docs
└── shared/                   ← both audiences
    ├── glossary.md           ← single source of term definitions
    └── diagrams/             ← reusable Mermaid files

What this is not

• An awesome list of every documentation tool
• A replacement for Confluence/CCMS in regulated enterprise publishing
• A SaaS or static site generator
• A general “how to run your company” handbook

See appendix/ecosystem-comparison.md to understand how this primer relates to Write the Docs, Google Tech Writing, Diataxis, C4 Model, adr-tools, and other documentation resources.

When this kit may hurt

• No engineers / no Git workflow — the overhead of PRs and folders will slow you down; use a simpler handbook tool until you have DocOps capacity.
• One-off disposable prototype — a single README may be enough; adopt the scaffold when the system will live.
• Heavy regulated authoring needing CCMS features first — you can still use Git backends later; do not force this tree alone if your compliance tooling cannot ingest it yet.

License

MIT — see LICENSE.