Agent Wranglers

Documentation Required

Change the docs in the same pull request

Keep docs in the repository next to the code they describe, and update them in the pull request that changes the behaviour.

By Erik Bergstedt, Agent Wranglers. Updated .

How to do it

Store docs as Markdown in the repository, in docs/ or beside the module. Never keep the only copy in a wiki that a pull request cannot change. Add a line to the pull request template that asks which doc changed. Map code folders to the docs that describe them, and let CI warn when one changes without the other. Allow a no-docs label for changes that alter nothing a reader sees.

Example

docs-follow-code:
  - code: src/billing/
    docs: docs/billing.md
  - code: src/api/
    docs: openapi.yaml

How to check

CI fails a pull request that changes a mapped code folder without changing its doc, unless the pull request carries the no-docs label.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/docs-with-the-change.