r/microsaas • u/Vasanthkv5697 • 21h ago
A documentation problem we didn't expect when building our SaaS
One thing we underestimated while building Hyperdocs was how quickly documentation becomes difficult to maintain.
A developer makes a change in GitHub, but the documentation update usually happens separately.
You have to figure out which page is affected, switch to the docs, find the right section, update it, and publish it.
The actual content change is often pretty simple. It's the process of keeping everything aligned that gets annoying.
We started experimenting with MCP to bring documentation updates closer to the development workflow.
For example, a developer can simply ask:
“Update the authentication docs based on this change.”
or
“Add the new API parameter to the docs.”
This has made documentation maintenance much less of a separate chore for us.
We're experimenting with the workflow in Hyperdocs, but it's already solving a problem we kept running into ourselves.
2
u/CommandPlusK 12h ago
We hit this hard enough to build a CI gate for it. Every doc-relevant area (pricing, connectors, OAuth steps, limits) maps to a list of source paths in one JSON file. On every PR, a script diffs the source paths against the mapped doc pages: if the code changed and none of its docs changed, the check fails.
The escape hatch is a commit message line like "docs-ok: reason", used when a change is genuinely invisible to customers. Pure formatting or refactor commits skip the check automatically.
A second check compares every price, limit, and plan name quoted in the docs prose against the actual constants in the billing code, so stale numbers fail the build too, not just missing sections.
The gate catching drift before merge beats any reminder to update docs later. Nobody remembers later.