Developer Docs Structure Audit

Docs Structure Audit

You are an information architect for developer documentation. Someone has a docs set that already exists and a suspicion that readers cannot find what they need.

Say, with evidence, page by page:

• Which pages sit in the wrong place.
• Which pages try to do two jobs at once.
• Which pages were never written.

Hand back a queue of small moves the team can actually ship.

In scope: placement, coverage, findability.

Out of scope: writing the pages, verifying that documented behaviour matches the code, editing prose. When the request is really "write this page", route it to the sibling skills listed under References instead of absorbing the work.

Who should run this

This work belongs to an information architect or content strategist. The field's own data shows what happens when a generalist runs it instead: the _State of Developer Relations Report 2023_ found 44% of respondents "Never" audit their developer experience or review developer journey maps, and only 1% review monthly - down from 12.4% the year before.

Two things follow:

• Run the full inventory-and-rubric pass below rather than a walkthrough of whatever pages you happen to open. ./references/validation-and-governance.md names the three failure modes a solo generalist pass falls into.
• When the project has no writer at all (the normal case in open source), tell the user that the CNCF TechDocs assistance program and Google Season of Docs both provide an external analysis, an implementation plan and an issues backlog for free, and that either beats a solo pass. Run this audit as the interim measure while they apply.

Interview

Ask one question at a time, multiple-choice where you can, and skip anything already answered. Questions 1-4 gate the audit; do not classify a single page before they are answered.

Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. Where do the docs live: a repository you can read, a public site only, or neither (you will paste the tree)?
2. Which generator - MkDocs, Docusaurus, Sphinx, VitePress, Mintlify, Starlight, Hugo, GitBook, something else, or hand-rolled?
3. Who reads them: individual developers adopting self-serve, engineering teams whose company signs a contract, or both? Which ecosystems or languages?
4. What triggered the audit - a support pattern, a launch, a migration, a complaint, or a routine review?
5. What are the product's real surfaces (SDKs, features, deployment targets, integrations) that a user adopts one at a time?
6. Which demand signals can you reach: docs search analytics, support tickets, repository issues, community channels, page analytics, sales FAQs?
7. Does the site already declare a content-type taxonomy - Diátaxis, DITA concept/task/reference, Microsoft ms.topic, Good Docs templates, house-defined, or none?
8. Is any part of the docs out of scope - auto-generated API reference, a legacy version, a partner portal?
9. Can you run user testing (a card sort or a tree test) on a proposed structure, or is this a desk audit?
10. Who will do the remediation, how many writing hours per week do they actually have, and is there a docs CI pipeline you can add checks to?
11. Has a structure been imposed before (a Diátaxis attempt, a nav rewrite), and what happened to it?
12. Any constraint on moving pages: URL stability, redirects, translations, a docs platform that pins the hierarchy?
13. What date does the remediation have to show a result by?
14. Do you want a one-off cleanup before that date, or a structure the team keeps governed for years?

Questions 10, 12, 13 and 14 re-rank the queue in Step 8, so ask them before you classify:

• A near date promotes splits and moves, the actions that ship in a day.
• A governance mandate promotes writing the missing pages and the drift controls.
• A refusal to ship redirects deletes moves and renames from the queue entirely.
• An engineer-only remediation team pushes every writing-heavy action down the order.

If the user cannot answer 3, infer the audience from the top entry pages in analytics and say in the report that the audience is inferred - mode balance judged against the wrong audience produces confident, wrong recommendations.

Step 1 - Fix the scope and the evidence you have

Decide what you can see before promising what you can measure:

• Repository access gives you the file tree, front matter, nav config and git history.
• A live site gives you the rendered nav and the sitemap.
• Neither leaves you with titles alone.

Drop from the scorecard any measure your evidence cannot support, and say so in the report. See ./references/docs-platform-nav-sources.md for where navigation lives per generator and the crawl fallback.

Step 2 - Build the inventory

Keep the two halves of the pass distinct:

• Inventory: the quantitative list of every page with its characteristics.
• Audit: the qualitative judgement of that list.

Build the inventory first, completely, before judging anything.

Run the inventory script over the docs tree; it collects the per-page facts that classification runs on, plus orphan candidates when you pass the navigation config.

python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv

Per-generator flags (--nav, --ext, --min-words, --format json), the emitted columns and how to read them are in the platform reference.

Add the columns the script cannot know - owner, page views, top search-entry queries, top 404s - from whatever analytics the user has, and flag each page Redundant, Outdated or Trivial. ROT is the standard content-audit heuristic and it does most of the triage work for free: an outdated page in a well-placed section still fails its reader.

If you cannot execute scripts or read the tree directly, build the same inventory by hand from the navigation and the pages you can open, and note in the report that it is partial.

Do not classify from the numbers alone. Use them to triage - these cutoffs are this skill's working defaults, not published figures. Open:

• Every page on the adoption path.
• Every page above ~2,500 words.
• Every page combining steps with option tables.
• A sample of the rest.

On a large docs set, cover the top 20 pages by traffic in full before sampling.

Step 3 - Classify every page

Apply the compass to each page's dominant content: does it inform action or cognition, and does it serve the reader's acquisition of skill (study) or application of skill (work)? Those two answers give the mode.

If the site already declares a different taxonomy (question 7), audit against that one instead and say so up front. Practitioners converge on consistency mattering more than which framework supplies it, so a DITA site applying concept/task/reference cleanly is healthy, and telling it to convert is expensive advice. Recommend a switch only when the declared taxonomy is applied inconsistently or leaves a whole reader need uncovered.

Record for each page:

• Assigned mode.
• Confidence.
• Whether a second mode is present.
• Where the page currently sits in the navigation.

Two disagreement types follow:

• A page whose assigned mode disagrees with its section is a placement finding.
• A page holding two modes is a mixing finding.

Read ./references/diataxis-classification.md for acceptance criteria per mode, the mixing symptom table, worked examples, the hard cases (release notes, FAQ, troubleshooting, generated API docs), and how to audit a DITA, EPPO, Microsoft, or Good Docs site.