An engineer changes the software and forgets to update the documentation. The system moves on, but the written explanation stays behind. A page can still look authoritative while describing behavior that no longer exists.
I built a workflow to keep that gap from opening in the systems I work on. When my agents change the software, updating its documentation is part of their work.
When stale docs become a business problem
The documentation I maintain explains how a technical system works. That understanding matters to the people directing the business: it informs what they think the software can do and what they decide needs to change.
Misleading documentation can send that work in the wrong direction. A decision can make sense according to the docs and still be based on an incorrect picture of the system. Keeping the description accurate is part of maintaining the software.
Making documentation part of the change
The engineering agent has the relevant context while it’s doing the work. When an implementation changes, a requirement gets clarified, or a new requirement emerges, it sends that context to a dedicated documentation agent through MCP.
The receiving agent updates the relevant documentation to reflect the system’s behavior. I usually keep those docs in Obsidian, though I’ve also used Notion. The updates happen automatically as part of the agent workflow.
This makes maintaining the documentation an explicit responsibility in the development process. The context passes directly from the agent doing the engineering work to the agent updating the written account.
For lessons about working with me, I use a different workflow that updates the agents’ own instructions.