docs-as-code
/docs-as-code
Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.
- Author
- Amey-Thakur ↗
- Repository
- AI-SKILLS ↗
- Licence
- MIT
- Last repository change
- 05.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.
Original author description
Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.
How it works
- Method
- Boundaries
SKILL.md preview
--- name: docs-as-code description: "Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow." --- # Docs as code The reason docs go stale is that they live apart from the code they describe, changed by different people through a different process. Docs-as-code closes that gap: documentation lives in the repo, changes in the same pull request as the code, and CI checks it: so drift becomes a build failure instead of a discovery months later. ## Method 1. **Keep docs in the repo, beside the code.** Markdown (or the docs framework's format) versioned with the source: the docs for a feature live next to it and change in the same commit. This co-location is the whole idea: the documentation and the code share one history, one review, one source of truth (see monolith-first's co-location instinct, applied to docs). 2. **Change docs in the same PR as the code.** A change that alters behavior updates the docs in the same pull request, reviewed together (see pull-request-size, code-review): the reviewer checks that the docs match the change while both are fresh. Separate docs-later tickets are how docs fall permanently behind. 3. **Check docs in CI.** Link checking (dead links fail the build), spell/style linting (see style-guides), and crucially, testing that code examples actually run (see api-reference-docs, tutorial-writing): a broken example fails CI like a broken test. Automated checks are what make "docs match reality" enforceable rather than aspirational. 4. **Build previews on every change.** A rendered preview of the docs per pull request (the framework deployed to a preview URL) lets reviewers see the actual output, not the raw markup: catches formatting breaks and reads the way users will. Reviewing docs as source is like reviewing a rendered UI as HTML. 5. **Generate what should be generated, write what should be written.** API reference from the schema (see api-reference-docs), CLI help from the parser, config options from the code: generated so they never drift; conceptual guides, tutorials, and rationale hand-written because no generator produces insight. Know which is which and wire the generation into the build. 6. **Lower the contribution barrier.** If fixing a typo requires learning a bespoke CMS, typos stay; if it is a markdown edit in the repo with a preview, anyone fixes it (see community-building's contributor ladder). The docs-as-code payoff includes that the whole team, not a docs silo, keeps docs current. ## Boundaries - Docs-as-code fits developer-facing and technical docs well; end-user documentation with heavy media, localization, and non-technical authors may need a CMS or hybrid: match the tooling to who writes and reads. - The workflow's value depends on the CI checks being real (tested examples, link checks): docs-in-the-repo without the checks is just a different place for stale docs to live. - Generated docs still need curation (see api-reference-docs); "generate everything" produces complete, correct, and unhelpful reference. The method is generate-plus-write, both in the repo.
Versions
The database has no other skills named docs-as-code.
Database snapshot: 13.11.2026 · package version d5d7502f34e4 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100update-ui-inventory
Update the UI component inventory and documentation when components are added or removed. Use when adding new components, after code reviews flag inventory mismatches, or periodically to ensure docs match reality. - 100cpp-review
Review C++ code against Google C++ Style Guide. Use when reviewing C++ code, pull requests, or when asked to check code style compliance. - 100docs-maintenance
Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current. - 100repo
Update repository documentation (README.md, docs/, CLAUDE.md) based on session changes by dispatching the up-docs-propagate-repo sub-agent. This skill should be used when the user runs /up-docs:repo. - 100docs-review
Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files. - 100update-docs
Update public documentation in docs/public/ when features or tools change. Triggers on "/update-docs", "update docs", "update documentation".