The problem this solves
Documentation is many products' most-visited marketing surface and least-managed one. It grew page by page as features shipped, organized by whoever wrote each section, and now holds excellent answers that neither humans nor machines can reliably find. Users search and land on the wrong page; support fields questions the docs already answer; and the deep pages that would convert an evaluating developer sit orphaned three clicks from anywhere.
The machine side of findability has quietly become the bigger stake. Developers increasingly ask AI systems how to do things, and those systems answer from whatever documentation they could parse, structure, and cite. A docs site with unclear hierarchy, thin metadata, and wandering page structure gets represented badly or gets skipped for a competitor's cleaner corpus, which means the docs' quality stops mattering at exactly the moment of the question.
Overhauls stall because the honest fix has two speeds: an information-architecture rethink that needs discussion and ownership, and a set of mechanical improvements that need nobody's permission beyond a code review. Bundling both into one initiative means the quick wins wait on the restructure debate, and usually die there. This playbook unbundles them: the restructure arrives as a proposal in Notion where it can be argued properly, and the five highest-value mechanical fixes arrive as an open PR the same day, with nothing merging itself.
How the mission runs
- Audit findability for humans. Site Audit crawls the docs site and maps its structural reality: hierarchy depth, orphaned pages, internal linking patterns, metadata quality, and how the site's search-facing signals compare to what its content deserves. The output is a concrete map of where good answers are hiding.
- Audit citability for machines. AI Visibility assesses how AI systems currently parse and cite the docs: which pages get used in answers, which get skipped, and what structural choices - heading discipline, page scope, extractable structure - are suppressing citation. This is the audit most docs sites have never had.
- Design the restructure proposal. The findings become an information-architecture proposal: a revised hierarchy, consolidation of overlapping pages, rescue paths for orphaned content, and conventions for page scope and structure that serve both search and citation. Every recommendation ties back to specific audit evidence, so the debate that follows argues with findings rather than taste.
- Write the proposal into Notion. The restructure lands in Notion as a working document: current state, proposed state, the reasoning per change, and a suggested migration order. Placed where the docs team plans, it is built to be argued with, amended, and eventually owned by the people who will live in it.
- Ship the five quick wins as a PR. Independent of the restructure debate, the five highest-value mechanical fixes - the metadata, linking, and structure changes that need no architectural decision - arrive as a pull request on GitHub, each commit explained. Review and merge stay with your team, and nothing merges itself.
The prompt
This is the exact objective the agent receives. Swap the obvious placeholders for your own domain, segment or channel and run it as-is from the console, Slack, or the API.
What comes back
Two artifacts on two speeds: a Notion proposal holding the full findability restructure - revised hierarchy, consolidations, orphan rescues, and structural conventions, each tied to audit evidence - ready for the docs team to debate and own; and an open pull request delivering the top five quick wins that need no architectural decision, each commit explained and waiting on your review. The overhaul starts shipping the day the debate starts.
Make it yours
- Run the citability audit against a competitor's docs as well, so the Notion proposal shows the gap you are closing rather than an abstract standard.
- Re-run the audit a month after the restructure ships, measuring whether orphan counts, search-facing signals, and citation patterns actually moved.
- Extend the quick-wins PR into a series: once the first five merge cleanly, the next tranche of mechanical fixes arrives the same reviewable way.
Frequently asked questions
Why split the restructure from the quick wins?
Because they move at different speeds and die when bundled. The restructure needs discussion, ownership, and a migration plan, which takes weeks; the mechanical fixes need a code review, which takes an afternoon. Splitting them means the audit starts paying for itself immediately while the bigger debate runs its course.
How were the five quick wins chosen?
By value against independence: the fixes that most improve findability or citability while requiring no architectural decision anyone might reverse. Each commit in the PR states the audit finding it addresses and why it is safe regardless of how the restructure debate concludes, so review is fast.
Who ends up owning the restructure?
Your docs team, deliberately. The Notion proposal is written to be amended: reasoning stated per change so disagreement is cheap, migration order suggested rather than imposed. An information architecture only works if the people maintaining it believe in it, and the proposal is built to earn that rather than assume it.