Category: Documentation

How Principal Engineers Shape Documentation as a Product + Punch List Lagniappe

I’ve written plenty about documentation already (just recently here and here), so consider this a continuation of that thread. If you missed the earlier pieces, I’ll drop placeholders for them at the end. For now, let’s talk about a role that quietly makes or breaks the whole idea of “documentation as a real product” inside an engineering organization: the principal engineer.

People love to treat documentation like something you toss over the wall to a tech writer or leave in a Jira ticket until someone “has time.” A principal engineer doesn’t get to play that game. If anything, they’re the last person who can afford to pretend docs are an afterthought, because they’re the ones who end up carrying the blast radius when those docs fail. And they will fail if the principal engineer isn’t shaping them with the same rigor they apply to architecture, APIs, and operational design.

A principal engineer isn’t writing every page. They’re not your documentation vending machine. What they do is far more structural. They set the expectations for how documentation fits into the engineering lifecycle. They define the standard for what good looks like. They remove ambiguity. They make it impossible for other engineers to shrug and say, “I didn’t know that needed to be documented.” And they act as the connective tissue between engineering, product, and whoever else depends on what the system actually does versus what people assume it does.

Continue reading “How Principal Engineers Shape Documentation as a Product + Punch List Lagniappe” →

AI Is Forcing Docs To Finally Grow Up

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

  1. Clear, hierarchical structure using consistent headings
  2. Small, semantically meaningful chunks that can be indexed cleanly
  3. Realistic examples, not toy snippets
  4. Explicit pathfinding: quickstart, deeper guides, reference, troubleshooting
  5. Direct language without fluff
  6. Predictable URLs and logical navigation trees
  7. Copy-pastable awexamples that actually work
  8. Strong inbound and outbound linking
  9. No PDF dumping ground
  10. Schema, config, API, and CLI references that are complete, not partial
  11. Contextual explanations right next to code samples
  12. Versioning that doesn’t break links every release
  13. Upgrade guides that don’t pretend breaking changes are rare
  14. A single authoritative source of truth instead of fractured side systems
  15. 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

https://stripe.com/docs/api

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

https://developer.mozilla.org

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

https://supabase.com/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.

Treating Documentation as a Product

Why It Works When You Actually Treat It Like One

I’ve been around the WriteTheDocs community for years now. Back in my Portland era I’d drop into meetups, follow along with the conference sessions, and talk shop with the folks who actually spend their careers obsessing over how information is communicated. It was always one of the more grounded communities in tech. Good people, smart conversations, very little fluff. I’ve been keeping an eye on it ever since and I fully plan to attend WriteTheDocs PDX in May 2026. I might even submit a talk because this topic is threaded through every role I’ve ever had. Whether I was working as a software architect, engineer, senior engineer, or principal, documentation has always been one of the core parts of building a product. I (often the odd one out in a group) put the same effort into it as I do the system itself.

A colorful illustration of a bookshelf filled with various books in different bindings and sizes, accompanied by a potted plant.

The problem is that much of the industry still doesn’t. For years we talked a big game about documentation being a product. But let’s be honest, outside a few disciplined teams, it was almost never treated that way. Docs were usually the afterthought stapled onto a release cycle. The task no one wanted but everyone relied on. The checkbox that got marked complete because someone copied three paragraphs from last quarter’s release notes and called it good. Then everyone wondered why onboarding took forever, why API integrations were painful, and why new features confused the very people who asked for them.

If you want documentation to work, you have to treat it like something you’re actually shipping. Same level of ownership. Same level of rigor. Same willingness to iterate. And if you do that, documentation transforms from the chore no one wants to the multiplier that accelerates everything else.

Documentation As A Product Means You Design It

When engineers build a product, we design it. We plan its architecture. We define the user paths. We ask who the audience is and what success looks like. Documentation deserves the same treatment. Successful doc systems start with questions that almost no one bothers to ask.

Who is going to read this
What do they already know
What do they not know
What is the first step they need to take
Where do they get stuck
What is the fastest path to seeing value
Where do we expect them to go next

If you can’t answer these questions, you’re not writing documentation, you’re just writing. Docs that work begin with intent. Docs that fail begin with copying old content forward.

Documentation As A Product Means You Build For Multiple Audiences

Good documentation isn’t simply written for “developers.” That’s too vague to be useful. In reality you’re writing for:

New engineers who need orientation
Experienced engineers who need specifics
Integrators who need references and guarantees
DBAs who need schema clarity and version guarantees
API consumers who need examples they can copy
Architects who need conceptual models
Support engineers who need troubleshooting steps
Automation and AI tools that need structure and clarity

When you treat documentation as a product, you give each of these audiences a space to succeed. Quickstarts for the eager. Deep reference for the precise. Tutorials for the wandering. Troubleshooting for the frustrated. A consistent navigation system so someone can land anywhere and still understand where they are. Just like designing any other user experience, you build around the people who will use it.

Documentation As A Product Means It Lives Alongside The Code

Illustration of a multi-shelf bookcase filled with various colorful books and a small vase of flowers on the top shelf.

Docs fail when they drift away from the system they describe. Good doc ecosystems don’t allow that drift. They sit next to the codebase. They live in the same repository or at least the same release process. Their updates are reviewed with the same seriousness as code changes. If an engineer lands a breaking change, they land the documentation change at the same time.

When a team builds documentation like this, the docs stop being “that section of the website marketing owns” and start becoming the authoritative source of truth for how things actually work.

Documentation As A Product Means You Measure It

Products have metrics. Documentation should too. Not vanity metrics like page views. Real impact questions.

Where are users dropping off
What pages bounce the most
What searches return nothing
What code samples fail
What parts cause the most support tickets
Which tasks take longer than they should
Which tutorials don’t get completed

Treating documentation as a product means observing it like one. If your docs don’t guide users to success, they are broken. And when you treat them as a product, you can fix them with intent rather than panic.

Documentation As A Product Means You Build A System, Not Pages

Most teams think documentation is pages. It isn’t. It’s a system. It’s:

  • Information architecture
  • Naming conventions
  • Templates for consistency
  • Semantic structure
  • Reference models
  • API style guides
  • Example libraries
  • Versioning strategies
  • Release processes
  • Deprecation policies
  • Tooling to validate all of the above

Software and database engineers already understand the importance of systems. Documentation is no different. You don’t get great docs from one brilliant writer. You get them from a disciplined ecosystem that supports many contributors producing consistent results.

Documentation As A Product Means You Iterate Continually

A colorful bookshelf filled with various books of different sizes and colors, alongside a small potted plant.

Documentation isn’t an end state. It’s ongoing stewardship. You refine the structure. You rewrite sections that have aged out. You incorporate user feedback. You evolve examples as best practices shift. You clean up conceptual models that no longer match reality. You fix gaps that AI or customers reveal. You refactor inconsistencies.

The same way good teams refactor code, good documentation teams refactor content. Not because it’s broken, but because clarity can always be improved.

Documentation As A Product Means Engineers Own It

Finally, the uncomfortable truth. Documentation is strongest when engineers contribute to it and weakest when engineers avoid it. Technical writers are incredibly valuable, but they’re not mind readers. If engineering doesn’t actively participate, documentation decays fast.

When engineers see documentation as part of delivering a feature, not a separate step after the fact, the quality of the entire product goes up. Every broken assumption gets caught sooner. Every user path becomes clearer. Every integration becomes easier.

That’s what treating documentation as a product looks like. Ownership, intent, design, iteration, metrics, and systems thinking.

A collection of colorful books arranged on shelves, with some plants and decorative items, illustrating an organized and inviting reading space.

This Is Not A New Movement, But The Stakes Are Higher Now

The WriteTheDocs community figured all of this out a decade ago. They’ve been shouting it from Portland rooftops every year. The only difference today is that the industry can no longer pretend documentation quality doesn’t matter. With AI systems consuming docs alongside humans, structure and clarity aren’t optional. Expectations are rising. Teams that do this well will stand out immediately because everything around their product becomes easier.

The elephant in the room, documentation has always been a product, the key to successful documentation is developing it as such!