Skip to content
Docs-as-Code Primer
Esc
↑↓navigate↵open⌘Jpreview
On this page

First week pack

Use this after you copy [`scaffold/`](scaffold/) into your repository. Goal: a **usable** docs spine in about one working week for a small team — not every folder filled.

First week pack

Use this after you copy scaffold/ into your repository. Goal: a usable docs spine in about one working week for a small team — not every folder filled.

Day 0 — Copy the kit (≤ 30 minutes)

  1. Copy into your repo root (adjust if monorepo):
    • scaffold/docs/ → docs/ (includes GOVERNANCE.md + KIT.md)
    • scaffold/.github/workflows/docs.yml
    • scaffold/.github/PULL_REQUEST_TEMPLATE.md (merge if you already have one)
    • scaffold/AGENTS.md
    • scaffold/.markdownlint.json
    • Optionally scaffold/llms.txt.example → llms.txt
  2. In the product repo, open docs/KIT.md and set KIT_URL to this primer repo (clone path or GitHub URL).
  3. Read docs/GOVERNANCE.md (stub policy) and this file (you can keep a bookmark to FIRST_WEEK.md upstream).
  4. Canonical map while working from the kit: appendix/phase-folder-map.md. In the product repo, use the path names listed in docs/KIT.md unless you vendor the map.

Minimum files to make real (the “7+” pack)

Fill or replace these first. Everything else can stay as folder READMEs until the phase arrives.

# Create / fill Template or example
1 docs/internal/charter/vision.md templates/vision-charter.md · Acme vision
2 docs/internal/charter/scope.md same template (Scope section)
3 docs/shared/glossary.md start from scaffold glossary · Acme glossary
4 One user story under docs/internal/requirements/ templates/user-story.md · Acme story
5 At least three NFR rows in docs/internal/requirements/non-functional.md templates/nfr.md · Acme NFRs
6 One ADR in docs/internal/decisions/ templates/adr.md · Acme ADR-001
7 docs/user/getting-started/quickstart.md Acme quickstart
8 (If you expose an API) one module spec + OpenAPI stub Acme export-service · OpenAPI sample

Optional the same week if you already page on-call:

+ File Example
9 One symptom runbook under docs/internal/operations/runbooks/ Acme queue backlog

What you may ignore in week 1

Per scaffold/docs/GOVERNANCE.md:

  • Empty phase folders beyond the files above
  • coverage-reports/, performance-benchmarks/, changelog history, retirement docs
  • Publishing to MkDocs/Docusaurus/Mintlify — enable scaffold/.github/workflows/docs.yml lint/link first; site recipes come later

Definition of done for week 1

  • docs/KIT.md has a real KIT_URL (or an explicit local path note)
  • Charter vision + scope committed
  • Glossary has product-specific terms (not only kit defaults)
  • At least one testable user story + numeric NFRs
  • At least one ADR for a real decision (or a “proposed” ADR for an open decision)
  • User quickstart exists (even if “coming soon” sections are marked TODO)
  • Docs CI workflow runs on PRs that touch docs/
  • PR template docs checklist is in use
  • No broken ../primer/... (or similar) links inside copied docs/ files

Next

Was this page helpful?