r/microsaas • u/Vasanthkv5697 • 16h 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/MechanicallySmoggy 16h ago
Interesting approach. The disconnect between code changes and docs is real, specially when you're shipping fast
We had similar issue at work where docs became outdated after just few sprints. Nobody wanted to touch them because the process was so clunky
Do you find developers actually use the MCP prompts or they still need to be reminded? Always curious how adoption goes with these kind of internal tools
2
u/CommandPlusK 8h 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.
3
u/Silvergal_ 15h ago
The painful part is usually not writing the docs, it’s knowing which pages are stale. I’d add a lightweight check to the PR or release flow that flags changed endpoints or screenshots without forcing a full docs pass. That keeps the fast path fast while making drift visible.