Is our product documentation actually helping or hurting our AI visibility? How should docs be structured?

Your JavaScript problem is likely the culprit. Here’s the technical reality:

How AI crawlers differ from Googlebot:

Your React doc site:

If content is loaded via JavaScript after page load, AI crawlers see:

<div id="root"></div>

Instead of your actual documentation.

Solutions (least to most effort):

1. Pre-rendering/SSR - Render pages server-side so HTML contains content
2. Static site generation - Build docs to static HTML files
3. Hybrid approach - SSR for critical pages, client-side for interactive elements

Quick validation:

1. View page source (not inspector) on your doc pages
2. If you see actual content = good
3. If you see empty divs = AI sees nothing

Framework options:

• Docusaurus (static + SSR)
• GitBook (pre-rendered)
• Mintlify (static)
• VitePress (static)

All generate HTML that AI crawlers can read.

Beyond the JS issue, let’s talk about structure optimization:

Documentation structure that AI loves:

1. Clear heading hierarchy

H1: Feature Name
  H2: What is [Feature]?
  H2: How to Use [Feature]
    H3: Step 1
    H3: Step 2
  H2: Troubleshooting
  H2: FAQ

2. Answer-first content Each section should lead with a direct answer, then explain:

Good: “To install Product X, run npm install productx. This command downloads the package from npm and adds it to your dependencies.”

Bad: “When you’re ready to begin using our product, you’ll want to make sure everything is properly configured. First, let’s talk about dependencies…”

3. Self-contained sections Each H2 section should make sense extracted independently. AI may quote just one section.

4. Explicit definitions Don’t assume context:

• “Product X is a project management tool that…”
• “The API rate limit is 100 requests per minute”
• “SSO (Single Sign-On) allows users to…”

Schema markup for documentation - this is often overlooked:

Essential schemas for docs:

1. Article/TechArticle schema

{
  "@type": "TechArticle",
  "headline": "How to Configure SSO",
  "datePublished": "2026-01-01",
  "dateModified": "2026-01-05",
  "author": {
    "@type": "Organization",
    "name": "Your Company"
  }
}

2. FAQPage schema - For troubleshooting/FAQ sections

{
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I reset my password?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Go to Settings > Security > Reset Password..."
    }
  }]
}

3. HowTo schema - For step-by-step guides

{
  "@type": "HowTo",
  "name": "How to Install Product X",
  "step": [{
    "@type": "HowToStep",
    "text": "Open terminal and run npm install..."
  }]
}

Impact on AI:

Schema doesn’t guarantee AI citations, but it:

• Helps AI understand content type
• Makes information extraction easier
• Signals structured, reliable information
• Improves Perplexity ranking (~10% factor)

Implementation tip:

Start with FAQPage schema on your most-queried topics. It’s easiest to implement and highest impact.

Documentation SEO perspective with AI considerations:

What we changed in our docs:

URL structure that works:

Good: /docs/features/sso-configuration Bad: /docs/article/12345

Descriptive URLs help AI understand content before reading.

Internal linking:

Cross-reference related docs heavily:

• “Learn more about [related feature]”
• “See also: Troubleshooting [topic]”
• “Prerequisites: [other doc]”

This helps AI understand topical relationships and build confidence in your authority.

Freshness signals:

• Display “Last updated” dates visibly
• Use accurate lastmod in sitemaps
• Actually update content (AI detects substantive changes)

This thread has been incredibly helpful. Here’s my action plan:

Immediate (Week 1):

1. Validate JS problem - Done, confirmed view-source shows empty divs
2. Research pre-rendering - Looking at Prerender.io for quick fix
3. Prioritize top pages - Identify 50 highest-traffic docs for SSR

Short-term (Week 2-4):

4. Implement pre-rendering - Get HTML visible to AI crawlers
5. Add FAQPage schema - Start with troubleshooting section
6. Restructure top docs - Answer-first, clear headings

Medium-term (Month 2-3):

7. Platform evaluation - Should we migrate to static doc platform?
8. Full schema implementation - TechArticle, HowTo across site
9. Content audit - Ensure self-contained sections throughout

Success metrics:

• View-source showing actual content
• AI citation tracking via Am I Cited
• Increased doc pages in AI responses
• Specific doc URLs appearing in citations

The insight:

Our documentation could be our biggest AI visibility asset - it’s comprehensive, accurate, and authoritative. But none of that matters if AI can’t read it.

For other doc teams:

Check your view-source right now. If it’s empty, you’re invisible to AI regardless of how good your content is.

Thanks everyone!