Docs-as-code workflow

Docs-as-code means documentation lives in the same workflow as software: plain text, Git, review, automation. This page describes the minimal setup we use with clients.

Repository layout#

Keep docs in the product repo when the product is a single service. Use a dedicated docs repo when several products share one site.

docs/
  getting-started/
    quickstart.md
    authentication.md
  guides/
    webhooks.md
  reference/
    openapi.yaml
  _templates/
    tutorial.md
    how-to.md
.vale.ini
.github/workflows/docs.yml

The pull-request loop#

1. Branch. The engineer or writer opens a branch named after the ticket.
2. Write. Update or add the page in the same PR as the code change.
3. Check. CI runs style, link and code-sample checks.
4. Review. One engineer confirms accuracy. One editor confirms clarity.
5. Preview. A per-PR preview URL is posted as a comment.
6. Merge. Merging to main deploys the site.

Frontmatter#

Every page carries metadata that drives navigation, search and freshness checks:

---
title: Verify webhook signatures
description: Confirm a webhook came from us before you process it.
owner: "@payments-team"
last_reviewed: 2026-08-01
type: how-to
---

Definition of done#

A feature is not done until:

• The user-facing docs are updated in the same PR
• Any new API surface is in the OpenAPI spec with examples
• The changelog has an entry
• The docs preview has been checked on mobile