CodeAFKeep the docs in step with the code

Keep the docs in step with the code

A file watch notices every code change and updates the API docs to match, so the docs never fall behind.

Docs go stale one small change at a time. Update them one small change at a time.
  • the API reference
  • the CLI help page
  • the config file reference

Every team has a docs page that was right once. In this playbook a watch follows the source files, and whenever one changes it reads the change and brings the API reference up to date: new endpoints, new status codes, the error cases nobody wrote down. Nobody has to remember to do it, and the docs change in the same hour as the code.

Steps

Our repository, kvapi, is a small Go key-value API with its reference in docs/API.md.

  1. In the repository, run codeaf.
  2. Say what to watch and what to do, and press Enter:
Whenever any .go file in this folder changes, read the change, update docs/API.md so every endpoint and status code in the code is described, and tell me in one line what you documented.
  1. A card comes back: wants to watch for something · sync API docs, shares the day's $500.00 allowance · checked every 5 minutes, where · for this project. Press 1 (Watch for it).

What you see

The first pass after you set it up only notes how the files look now. In our run a teammate then committed kvapi: DELETE /kv/<key>. The next pass saw the change 12 seconds later and fired, and the chat said in one line that docs/API.md now documents DELETE /kv/<key> (204, and 404 for an unknown key) alongside GET and PUT and the 405 and 404 error cases, checked side by side with server.go.

The new section and an Errors section were in docs/API.md as an uncommitted edit, ready to commit with the code or on their own.

In our run

From the commit to updated docs took about 40 seconds, and the firing cost $0.005. Setting it up took longer than it needed to, about five and a half minutes and $0.08, because the chat first updated the docs once and read its manual before it offered the card.

Make it yours

  • Point it at any reference. A watch on cmd/** can keep the CLI help page current; a watch on the config loader can keep the config reference current.
  • Commit as it goes. Add "commit docs/API.md as docs: <what changed>" to the sentence if you want each update as its own commit.
  • Stop it. Say "stop the sync API docs watch" in any chat of the project and it shows retired. See Watches.

Go further

Watches: Say what you are waiting for; CodeAF looks on a timer and starts work only when the answer is yes.

Coming soon: describe the org you want and CodeAF builds it: teams, managers, budgets, standing orders.