What is docs as code?

Docs as code (also written documentation as code) is the practice of producing documentation with the same tools and workflow you use for software: plain-text source files in version control, changes proposed as pull requests, correctness enforced by automated checks in CI, and publishing done by a build step. The document in the repository is the single source of truth — the website, PDF, or slide deck is just a build artifact.

Why teams adopt it

The alternative — wikis, shared drives, design-tool canvases — fails the same way every time: documentation lives far from the code it describes, nobody reviews changes, and nothing tells you when a page goes stale. Moving docs into the engineering workflow fixes each of those structurally:

• Version control. Every change has an author, a diff, and a revert. Docs and the code they describe can change in the same commit.
• Review. Documentation goes through pull requests, so accuracy is checked by the people who built the thing — before publishing, not after a reader complains.
• CI validation. Broken links, invalid examples, and malformed content fail the build instead of shipping.
• One source, many outputs. The same source renders to a docs site, a PDF for the auditor, or slides for the review meeting.

The docs-as-code workflow

A minimal pipeline has four stages, and each maps onto a familiar software practice:

1. Write in a plain-text format — Markdown, almost always — in the same repository as the code.
2. Review through a pull request, like any other change.
3. Validate in CI: linting, link checking, and — if your format supports it — schema validation of the content itself.
4. Publish with a build command that turns source into a website, PDF, or slides.

Where classic docs as code breaks down

Prose survives this pipeline well. Everything else degrades. Diagrams get pasted in as screenshots that no diff can inspect and no check can validate. API tables drift from the handlers they describe. Roadmaps live in a slide deck two quarters behind reality. The parts of documentation most likely to be wrong are exactly the parts CI can't see.

Chiltepin's answer is to give the visual parts of a document the same rigor as the prose: anything visual is a typed block — a fenced section of Markdown with a type and a YAML body, validated against a strict schema. This sequence diagram is source code, not a screenshot:

```sequence
id: seq-place-order
title: Place order
endpoint: { method: POST, path: /orders }
actors:
  - { id: Client, name: Client }
  - { id: API, name: Orders API }
messages:
  - { from: Client, to: API, label: POST /orders, kind: sync }
  - { from: API, to: Client, label: 201 Created, kind: response }
```

There is a growing library of block types — sequence diagrams, ERDs, C4, flowcharts, state machines, Gantt charts, API endpoints, ADR-style decision records — and chiltepin check validates every block and every cross-reference, failing CI on errors. One command exports a static site, slides, or PDF. Your .md files stay the single source of truth.

Docs as code in the AI era

Docs as code turned out to be the right architecture for a reason nobody predicted: plain text is what AI agents are best at writing. But an agent that can write anything will also confidently write nonsense — which is why the missing half of AI-written documentation is verification. Because every Chiltepin block has a schema, an agent can write your docs and chiltepin check can prove they're structurally right, the same way a test suite gates AI-written code. You review content, not syntax. That's what we mean by AI-first docs as code.

Choosing docs-as-code tools

For prose-only documentation, a static site generator (Docusaurus, MkDocs, Hugo) plus a linter is a fine stack. Reach for Chiltepin when your documents are more than prose — when they need diagrams your agent can write and CI can validate, when the same source must ship as a website and slides and PDF, or when you're replacing an unvalidated diagram DSL (see Chiltepin vs Mermaid). It's MIT-licensed, and the whole editor runs in your browser with nothing uploaded.