Update docs when the code changes
When an API or setting changes, the docs get a matching update.
Engineering · Software · When something happens · Updated
Works with
- Slack
- Notion
- Confluence
- Box
Slack
Notion
Confluence
BoxHow do you update documentation when the code changes?
To update documentation when the code changes, set a Loop in Maito that starts when a pull request opens. It reads what changed in the API or settings, commits matching edits to your docs files, and checks Notion, Confluence or Box pages that still describe the old behavior. It lists those edits for you to approve.
How it's done today
Docs drift behind the code.
What Maito does
- Read the change
- Find docs that describe it
- Draft the doc update in the same PR
Example
Loop run: Pull request opened · #877 Add status filter to GET /v1/invoices
PR #877 changes GET /v1/invoices. I added a docs commit to the pull request. • New ?status parameter: draft, open, paid, void • Example response updated • The deprecated amount field is removed. That breaks existing clients. Changed: docs/api/invoices.md, 2 sections. Catch: the Notion page Invoices API guide still tells people to read amount in 3 places, and the Zapier example on it uses it too. Replacement text is ready in notion-invoices-edits.md. I haven't touched Notion. From the diff and the Notion page. Want me to apply the Notion edits once the reviewer approves the PR?
@Maito yes, once it's approved. And add a breaking-change note to the PR description.
Added the note to the PR description. I'll apply the Notion edits after approval and say so here.
Maito (11:36 AM):
PR #877 changes GET /v1/invoices. I added a docs commit to the pull request.
• New ?status parameter: draft, open, paid, void
• Example response updated
• The deprecated amount field is removed. That breaks existing clients.
Changed: docs/api/invoices.md, 2 sections.
Catch: the Notion page Invoices API guide still tells people to read amount in 3 places, and the Zapier example on it uses it too. Replacement text is ready in notion-invoices-edits.md. I haven't touched Notion.
From the diff and the Notion page. Want me to apply the Notion edits once the reviewer approves the PR?
Alex (11:52 AM):
yes, once it's approved. And add a breaking-change note to the PR description.
Maito (11:53 AM):
Added the note to the PR description. I'll apply the Notion edits after approval and say so here.
How to set it up
- Ask your agent
“When a pull request changes our public API, update the API docs in the same pull request. Also check the Notion docs for anything that now says the wrong thing, and post what you found in #eng.”
- Connect docs
- Notion
- Confluence
- Box
Not connected yet? Your agent sends you a link to sign in.
What it won't do
It finds the pages it is connected to. Docs kept somewhere else, or written in words that do not match the code, can be missed.
Questions
No. It prepares replacement text for pages in Notion, Confluence or Box and leaves the pages alone until you approve.
Into the same pull request, as a separate commit, so the reviewer sees code and docs together.
Yes. If a field is removed or renamed, it calls that out in the pull request comment.
