For years we talked a big game about documentation being “a product” (which I just wrote about yesterday right here) but let’s be honest, most of the industry never treated it that way. Docs were usually the afterthought stapled onto the release cycle, the box to tick for PMs, the chore no one wanted but everyone relied on. Then generative AI rolled in and quietly exposed just how brittle most documentation is. Suddenly the docs that were just barely acceptable for humans became completely useless for LLMs. That gap is now forcing organizations to rethink how docs get written, structured, published, and maintained.
The shift is subtle but fundamental. We’re no longer writing solely for people and search engines. We’r…
For years we talked a big game about documentation being “a product” (which I just wrote about yesterday right here) but let’s be honest, most of the industry never treated it that way. Docs were usually the afterthought stapled onto the release cycle, the box to tick for PMs, the chore no one wanted but everyone relied on. Then generative AI rolled in and quietly exposed just how brittle most documentation is. Suddenly the docs that were just barely acceptable for humans became completely useless for LLMs. That gap is now forcing organizations to rethink how docs get written, structured, published, and maintained.
The shift is subtle but fundamental. We’re no longer writing solely for people and search engines. We’re writing for people, search engines, and AI models that read differently than humans but still need clarity, structure, and semantic meaning to deliver accurate results. This new audience doesn’t replace human readers, it simply demands higher quality and tighter consistency. In the process, it pushes documentation to finally become the product we always claimed it was.
Why AI Is Changing How We Write Docs
AI assistants (tooling/agents/whatever) like ChatGPT and Claude don’t “browse” docs. They parse it. They consume it through embeddings or retrieval systems. They chunk it. They analyze the relationships between sentences, headings, bullets, and examples. When a user asks a question to an LLM, the model is leaning heavily on how well that documentation was written, how well it was structured, and how easily it can be transformed into a correct semantic representation.
When the docs are good, AI becomes the ultimate just-in-time guide. When the docs are sparse, meandering, inconsistent, or buried in PDFs, AI either hallucinate its way forward or simply fails. The AI lens exposes what humans have tolerated for years.
That is why companies are starting to optimize docs not only for readers and SEO crawlers, but for vector databases, RAG pipelines, and automated summarizers. The end result benefits everyone. Better structured content helps AI perform better and human readers navigate faster. AI becomes a multiplier for great doc systems and a harsh critic for bad ones.
What Makes Great Modern Documentation Now
Modern documentation can’t just be readable. It has to be machine digestible, SEO friendly, and human friendly at the same time. After picking through dozens of doc systems and tearing apart patterns in both good and terrible documentation, here is what consistently shows up in the good stuff.
The Criteria
- Clear, hierarchical structure using consistent headings
- Small, semantically meaningful chunks that can be indexed cleanly
- Realistic examples, not toy snippets
- Explicit pathfinding: quickstart, deeper guides, reference, troubleshooting
- Direct language without fluff
- Predictable URLs and logical navigation trees
- Copy-pastable awexamples that actually work
- Strong inbound and outbound linking
- No PDF dumping ground
- Schema, config, API, and CLI references that are complete, not partial
- Contextual explanations right next to code samples
- Versioning that doesn’t break links every release
- Upgrade guides that don’t pretend breaking changes are rare
- A single authoritative source of truth instead of fractured side systems
- Accessible to LLMs: consistent formatting, predictable patterns, clean text, no wild markdown gymnastics
Nothing magical here. Most teams already know these rules. AI just stops letting you ignore them.
Five Examples Of Documentation That Nails It
Below are five strong documentation ecosystems. Each one does something particularly well and gives AI models enough structure to be genuinely useful when parsing or answering questions. I’ll break down why each works and how it maps to the criteria above.
1. Stripe API Docs
Stripe has been the gold standard for a while. Even after dozens of competitors tried to clone the style, Stripe still leads because they iterate constantly and keep everything ruthlessly consistent.
Why it’s great • Every endpoint is its own semantic block. LLMs love that. • Request and response examples are always complete, never partial. • Navigation is predictable and deep linking is stable. • They pair conceptual docs, quickstarts, and reference material without overlap. • All examples are real world and cross language.
How it maps to the criteria • Structured headings and deep linking check 1, 6, and 12. • Chunking and semantic units check 2 and 15. • Real examples and direct language check 3 and 5. • Pathfinding is excellent which checks 4. • Copy-pasteable working examples check 7.
2. MDN Web Docs
MDN has decades of content, but it’s shockingly consistent, well-maintained, and semantically structured. It’s one of the best corpora for training and grounding AI models in web fundamentals.
Why it’s great • Long history yet content stays current. • Clear separation of reference vs guides vs tutorials. • Canonical examples for everything the web platform offers. • Clean, predictable markdown structure across thousands of pages.
How it maps • Nearly perfect hierarchy and predictable formatting check 1 and 15. • Chunked explanations with immediately adjacent examples check 2 and 11. • Stable URLs for almost everything check 6 and 12. • Strong pathfinding check 4.
3. HashiCorp Terraform Docs
https://developer.hashicorp.com/terraform/docs
Terraform’s documentation is extremely structured which makes it exceptionally machine readable.
Why it’s great • Providers, resources, and data sources follow identical templates. • Every argument and attribute is listed with exact behavior. • Examples aren’t fluff, they reflect real infrastructure patterns. • Cross linking between providers and core Terraform concepts is tight.
How it maps • The template system hits 1, 2, 6, 10, 11, and 15. • Cross linking and clear navigation cover 8. • Complete reference material covers 10. • Realistic examples check 3 and 7.
4. Kubernetes Documentation
https://kubernetes.io/docs/home
Kubernetes docs are huge, maybe too huge, but they’re structured well enough that LLMs and humans can still navigate them without losing their minds.
Why it’s great • Strong concept guides and operator manuals. • Structured task pages with prerequisites and step-by-step clarity. • Reference pages built from source-of-truth schemas. • Thoughtful linking between concepts and tasks.
How it maps • Strong hierarchy and navigation hit 1 and 6. • Machine readable chunks via consistent template patterns hit 2 and 15. • Clear examples and commands check 3 and 7. • Having both reference and conceptual breakdowns checks 4, 10, and 11.
5. Supabase Docs
Supabase’s docs are modern, developer-focused, and written with obvious attention to how AI and search engines consume content. They basically optimized for RAG without ever claiming they did.
Why it’s great • APIs, client libraries, schema definitions, and guides all interlink tightly. • Clear quickstarts that become progressively more advanced. • Rich examples spanning REST, RPC, SQL, and client SDKs. • Consistent layouts across different product surfaces.
How it maps • Strong pathfinding and multi-surface linking check 4 and 8. • Full reference material checks 10. • Predictable structure and formatting check 1 and 15. • Example-rich guides check 3, 7, and 11.
Documentation Is Finally Being Treated As A Real Product
The interesting thing is that AI didn’t magically fix documentation. It simply raised expectations. Companies now need their documentation to be clean, complete, structured, predictable, link-friendly, example-rich, and semantically coherent because that is the only way AI can navigate it and support users in meaningful ways. This pressure is good. It forces consistency. It rewards clarity. It makes the entire documentation discipline more rigorous.
The companies that embrace this will have far better support funnels, drastically fewer user frustrations, higher product adoption, and an ecosystem that AI can actually help with instead of stumbling through. The ones that don’t will keep wondering why users stay confused and why their AI chatbots give terrible answers.
Documentation has always been a product. AI is just the first thing that has held us accountable to that truth.