docs-as-code-intro

name	docs-as-code-intro
description	Use when introducing a team to Documentation-as-Code — explains the principle, the minimum toolchain (Markdown + Git + PR review + CI), and the first three steps to adopt it on an existing project.

Documentation-as-Code — Introduction

This skill is the entry-point lesson for adopting Documentation-as-Code (docs-as-code) on a real team. It is intentionally short: read it, then apply the three steps to one real document.

The principle

Treat documentation like source code.

Concretely, that means four habits:

1. Plain text — write docs in Markdown, not in binary editors. Diffable, greppable, durable.
2. Version control — every doc change is a Git commit, with history and the ability to revert.
3. Review via pull request — docs changes are reviewed the same way code is.
4. CI/CD — pushing triggers automated checks (broken links, structure, formatting) and builds.

Why it matters

• Docs stay in sync with code when they live beside it and change in the same pull request.
• Contribution barrier drops — anyone can fix a typo via a PR without special tooling access.
• Documentation becomes a first-class deliverable, not an afterthought.

The first three steps (apply to ONE document today)

1. Move it to Markdown in the repo. Pick one important doc (a runbook, an onboarding guide). Convert it to a .md file and commit it.
2. Open a pull request for the next change. Instead of editing in place, branch → edit → PR. Ask one teammate to review.
3. Add one CI check. Start with a link-checker or a Markdown linter that runs on every PR.

Worked example

See examples/nova-superapp/ for a complete super-app documented end-to-end in Markdown: a single feature traced from business need (BRD) all the way to test plan and inter-team API contract, with CODEOWNERS and a CI workflow.

Where to go next

• Define a CONTRIBUTING.md so contributors know the format and PR checklist.
• Add a docs site generator when README-only stops scaling (the kit recommends reusing an existing Markdown/MDX site, or Starlight for a dedicated site).