{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to review your docs navigation structure","description":"How to paste a sitemap or folder tree for AI review, which navigation mistakes models flag for new readers, and how Reunite visual pull request review validates a restructure before publish.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-review-your-docs-navigation-structure","__idx":0},"children":["Use AI to review your docs navigation structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Readers decide whether your API is approachable before they read a single endpoint description. They scan the sidebar, search for authentication, and bail when errors live three levels deep under a label that sounds unrelated. A large language model cannot replace analytics, but it can read your folder tree or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," outline and flag patterns that confuse first-time integrators."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This article shows what to paste into a navigation review, the problems that show up repeatedly, a before-and-after tree you can adapt from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]},", and how to validate the restructure in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/reunite"},"children":["Reunite"]}," before you merge."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-share-with-the-model","__idx":1},"children":["What to share with the model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste the structure readers actually see, not an internal wiki map. That usually means a folder tree from your docs repo, the ordered list from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/navigation/sidebars"},"children":["Sidebars configuration options"]},", or an export of your published sidebar labels."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a short persona block: who arrives cold this week, what they need to accomplish in the first session, and which pages you consider prerequisites. Without tasks, the model defaults to generic \"logical grouping\" advice."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note whether navigation is file-driven or explicit. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/navigation/navigation"},"children":["Navigation in Realm"]}," explains that missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," often means order follows the file tree, which may not match how you want newcomers to read."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prompt-template-for-a-navigation-review","__idx":2},"children":["Prompt template for a navigation review"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the prompt checklist-shaped so output is actionable in a restructuring PR."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are reviewing documentation navigation for a first-time API integrator.\n\nTasks they must complete in order:\n1. Create an account and obtain API credentials\n2. Authenticate and make a first successful request\n3. Handle common errors and rate limits\n4. Subscribe to webhooks for order updates\n\nReview the pasted folder tree and answer:\n1. Which tasks are hard to discover from the sidebar alone?\n2. Which sections are too deep (more than two clicks from a sensible entry point)?\n3. Which topics are split across unrelated top-level groups?\n4. Propose a revised tree with one-line justification per move.\n5. List assumptions about reader skill level.\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask for a table of moves rather than a full rewrite of every filename so authors can apply changes incrementally."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"problems-ai-often-flags-for-new-readers","__idx":3},"children":["Problems AI often flags for new readers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication buried under advanced guides is the classic miss. Integrators expect auth beside getting started, not under a catch-all reference folder they open only after a failed curl."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error and rate-limit content separated from the operations that trigger those responses forces readers to context-switch. Models often suggest moving error catalogs adjacent to API reference or linking them prominently from getting started."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples orphaned at the root while conceptual guides sit elsewhere make tutorials feel optional when they are the real on-ramp. Webhooks promoted to top level without a prerequisite auth page strand readers who land from search."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Orphan pages with no parent group show up when teams add files faster than they update ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/navigation/sidebars"},"children":["Sidebars configuration options"]},". Ask the model to list files that appear disconnected from any stated task flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-and-after-a-flat-top-level-layout","__idx":4},"children":["Before and after a flat top-level layout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The learn article on reviews uses a flat tree where foundational topics compete with reference material:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["docs/"," ","├── getting-started/"," ","├── api-reference/"," ","├── webhooks/"," ","├── authentication/"," ","├── rate-limiting/"," ","├── errors/"," ","└── examples/"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"\nA tighter shape for the same content groups onboarding, nests errors with reference, and tuck examples under guides:\n\ndocs/\n├── getting-started/\n│ ├── authentication.md\n│ ├── first-api-call.md\n│ └── rate-limits.md\n├── api-reference/\n│ ├── endpoints/\n│ └── errors.md\n├── guides/\n│ ├── webhooks.md\n│ └── examples/\n└── advanced/\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The moves are explainable in reader terms. Authentication and rate limits belong with first steps. Errors are reference material readers consult from operation pages. Examples are guides, not a peer of the API catalog."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your product names differ, but the pattern repeats: pull prerequisites up, push deep reference down, and reduce top-level siblings."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validate-the-restructure-in-reunite-before-publish","__idx":5},"children":["Validate the restructure in Reunite before publish"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["AI proposes moves. Humans still need to see rendered navigation with real labels and cross-links. Edit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," or move files in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/reunite/project/use-editor"},"children":["use the editor"]}," flow, open a pull request, and ask reviewers to use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/reunite/project/pull-request/review-pull-request"},"children":["review a pull request in Reunite"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Review tab opens in Visual view by default, showing rendered pages before and after your changes. That is the right place to confirm a moved auth page still reads well in context and that examples under guides did not break sidebar depth."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Toggle to Code when you need to verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," ordering line by line. Filter the file tree on large PRs so reviewers can focus on navigation files first."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat the visual diff as the acceptance test for the AI plan. If the sidebar still hides credentials behind three clicks in the preview, reject the merge even when the folder tree looks tidy in Git."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-ai-cannot-infer-about-your-audience","__idx":6},"children":["What AI cannot infer about your audience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models do not see search console data, support ticket tags, or which pages your sales team demos most. They may over-weight alphabetical order or symmetry when your readers arrive from one high-intent landing page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They also cannot know internal politics about which product name must appear in a top-level label. Use AI for reader-task fit; use stakeholders for naming commitments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":7},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paste the same sidebar order production uses, including hidden or draft sections you plan to publish soon."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List five to eight first-week tasks explicitly so the model judges discoverability against work, not aesthetics."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply navigation changes in a dedicated PR with only IA edits when possible so visual review stays focused."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-run the prompt after major feature launches because new guides often land as orphan files."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-approach-cannot-replace","__idx":8},"children":["What this approach cannot replace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach cannot replace quantitative path analysis, card-sort studies with real users, or accessibility review of navigation landmarks. It speeds structural critique before you invest in a full rework."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-pieces-fit-together","__idx":9},"children":["How the pieces fit together"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n T[Folder tree or sidebars.yaml] --> A[AI navigation report]\n A --> E[Edit structure in Reunite]\n E --> V[Visual PR review]\n V --> M[Merge and deploy]\n","diagramHtml":"

Folder tree or sidebars.yaml

AI navigation report

Edit structure in Reunite

Visual PR review

Merge and deploy

","diagramHtmlDark":"

Folder tree or sidebars.yaml

AI navigation report

Edit structure in Reunite

Visual PR review

Merge and deploy

"},"children":["graph LR\n T[Folder tree or sidebars.yaml] --> A[AI navigation report]\n A --> E[Edit structure in Reunite]\n E --> V[Visual PR review]\n V --> M[Merge and deploy]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The model narrows which moves are worth trying; Reunite visual review proves the sidebar works for humans."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":10},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you want Git-backed editing, pull request review, and side-by-side visual diffs on navigation changes, start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/reunite"},"children":["Reunite"]}," and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/reunite/reunite"},"children":["Reunite documentation"]}," hub for editor and review workflows."]}]},"headings":[{"value":"Use AI to review your docs navigation structure","id":"use-ai-to-review-your-docs-navigation-structure","depth":1},{"value":"What to share with the model","id":"what-to-share-with-the-model","depth":2},{"value":"Prompt template for a navigation review","id":"prompt-template-for-a-navigation-review","depth":2},{"value":"Problems AI often flags for new readers","id":"problems-ai-often-flags-for-new-readers","depth":2},{"value":"Before and after a flat top-level layout","id":"before-and-after-a-flat-top-level-layout","depth":2},{"value":"Validate the restructure in Reunite before publish","id":"validate-the-restructure-in-reunite-before-publish","depth":2},{"value":"What AI cannot infer about your audience","id":"what-ai-cannot-infer-about-your-audience","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What this approach cannot replace","id":"what-this-approach-cannot-replace","depth":2},{"value":"How the pieces fit together","id":"how-the-pieces-fit-together","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to review your docs navigation structure","description":"How to paste a sitemap or folder tree for AI review, which navigation mistakes models flag for new readers, and how Reunite visual pull request review validates a restructure before publish."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-review-docs-navigation-structure","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}