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!

Architects Evolving: How AI Is Reshaping the Role

In my last post, I broke down the many kinds of Software Architects, the ivory tower variety, the hands-on technical ones, and the practice architects who design how design happens. But here’s the thing: the role is shifting. The same forces that transformed how we build, deploy, and ship software are transforming what it even means to design (or “architect” as many say verb-izing the word) software.

We’re now entering an era where architects and principal engineers aren’t just bridging teams and systems. They’re orchestrating collaboration between humans and AI. The tools we use now think with us, and that changes everything about the craft.

The Changing Landscape

Ten years ago, a lot of architecture work was about managing complexity by building abstractions; frameworks, templates, deployment patterns. We spent weeks designing scaffolding so teams could build faster and more consistently. But that kind of work is getting automated. AI systems can generate scaffolding, boilerplate, and full service templates in minutes. The problem we used to solve, how to get started, isn’t really a problem anymore.

When the thing you used to design can now be generated instantly, the focus has to move. Architects aren’t defining structure anymore; they’re defining intelligence. You’re not asking “What should this system look like?” You’re asking “How do we make sure the AI knows why it should look that way?” It’s about shaping the inputs, context, and data so that what’s generated aligns with intent. The job shifts from building code foundations to engineering the thinking process that builds them.

The Rise of the AI-Literate Architect

We’re watching a new type of architect emerge: the AI-literate one. They still understand the core principles: separation of concerns, scalability, event-driven architecture, fault tolerance, all of it. But they also understand how generative systems influence those principles in real time.

An AI-literate architect knows how to embed architectural context into the ecosystem. They define how teams use AI-assisted tools safely and effectively. They make sure the AI understands the system’s constraints and style. They design for AI participation, not just human interaction.

This requires a mental shift. You stop thinking in one-way delivery lines and start thinking in loops. Human input feeds AI generation. AI output is validated and tuned by humans. That feedback updates the system and documentation automatically. It’s no longer a linear workflow, it’s a learning cycle. If you’re the architect, you design that cycle.

From Gatekeeper to Curator

In the old model, architects were the gatekeepers; reviewing, approving, enforcing standards through checklists and review boards. The problem is, AI doesn’t wait for review meetings. It just keeps generating.

That means the architect’s role evolves from enforcing architecture to curating it. You’re building adaptive systems that can evolve in real time while staying within safe boundaries. Architecture becomes an active process, not a static deliverable.

You start embedding your architectural intelligence directly into the system. Instead of writing 40 pages of guidelines that nobody reads, you teach the AI to enforce them. You build architectural context into templates, pipelines, and code generation rules. You define the patterns and anti-patterns that the tooling itself understands. It’s a shift from “humans enforcing rules” to “systems embedding rules.”

Practice Architects, in particular, are going to be the ones who make this leap first. They’ll design how AI participates in engineering: defining prompt libraries, training models on architectural standards, and creating governance systems that are continuous instead of ceremonial. Architecture review won’t be a meeting anymore; it’ll be a real-time feedback process that’s baked into every commit.

Bridging in the Age of Intelligent Systems

Architects and principal engineers have always been bridges between silos. That part doesn’t change it just gets more complex. Now you’re bridging not just Product, Engineering, and Operations, but also human and machine reasoning.

You’re designing how information moves between people, systems, and AI tools. You have to ensure that AI-driven design decisions stay aligned with business intent, because left unchecked, they’ll drift fast. AI is great at generating something that looks right but is completely wrong. So now part of the architect’s responsibility is to make sure the system learns properly and doesn’t hallucinate structure or logic that doesn’t exist.

This is where the role scales. Architects are no longer managing systems, they’re managing sociotechnical ecosystems. People, tools, code, feedback loops, all moving parts in one continuous adaptive system. That’s the new frontier.

The New Shape of Senior Engineering

Principal Engineers, Staff Engineers, and Architects are converging. The boundaries are blurring because the core responsibility is shifting toward orchestration of people, systems, and now AI agents. The job isn’t just designing systems; it’s designing the processes that generate and sustain them.

The most effective senior engineers in this new landscape are systems thinkers. They understand feedback loops, both technical and human. They can teach teams how to reason with AI and validate its output. They can embed governance and ethics into automation. And most importantly, they know how to keep humans in the loop without killing speed or creativity.

The point isn’t to resist AI. It’s to shape it, to make sure it becomes an extension of good engineering judgment, not a replacement for it.

The Path Forward

Software architecture isn’t fading away it’s evolving into something more dynamic. The diagrams and frameworks are still there, but now they’re part of a system that can reason about itself. The architect’s job is to make sure that system is learning the right lessons.

The best architects in this new era will stop treating architecture as documentation and start treating it as infrastructure. They’ll design processes that teach systems how to design themselves safely and intelligently. They’ll move from drawing boxes to defining the feedback loops between them. They’ll stop defending their ivory towers and start engineering adaptive ecosystems that learn and evolve continuously.

The next generation of architects won’t just design software. They’ll design intelligence into how software gets made. And that’s a far more interesting challenge.

Architects Among Us: The Many Shapes of Software Architecture

There’s a certain mystique that hangs around the title Software Architect. Some folks imagine a mythical being who levitates above the codebase, drawing circles and boxes on whiteboards, rarely touching a keyboard. Others see a burned-out senior developer who couldn’t let go of control, so they were promoted sideways. Both caricatures exist. Neither tells the whole story.

After years of designing systems, writing code, and watching teams rise and collapse under architectural decisions, I’ve realized that software architecture is less about diagrams and more about bridging people, systems, and time. It’s about building something that won’t rot under its own weight while still shipping what the business needs today.

The Job, at Its Core

A software architect’s real job is to balance competing forces. You’re thinking about performance, maintainability, developer experience, delivery velocity, and of course, cost. You deal in tradeoffs, not absolutes.

At its simplest, the role centers on three things:

  1. Defining the structure and intent of the system and what we’re building, and how it fits together.
  2. Guarding the integrity of that structure as it evolves.
  3. Communicating decisions clearly across the organization, from executives to developers.

It sounds straightforward until you’re six months into a project, two refactors deep, and someone in leadership just promised a feature that blows your architecture wide open.

The Many Flavors of Architect

There isn’t just one “Software Architect.” There are variations, each shaped by how close they stay to the code and how they interact with people and process.

The Ivory Tower Architect

This type rarely writes code and speaks in abstractions so detached from reality that teams can’t implement them without rewriting half the stack. The intentions are usually good, high-level vision, strong conceptual models,but the execution falls apart because they’re disconnected from how things actually get built and deployed. You’ll find them making PowerPoints, not pull requests.

The Technical Architect

This one’s hands-on. They know the quirks of the stack, the CI/CD pipeline, the caching edge cases, and which query in the database keeps locking under load. They’re the first to prototype, the last to stop tweaking configurations. They live closer to engineering and sometimes lose sight of business priorities, but when they’re balanced, they become the backbone of any effective engineering effort.

The Practice Architect

This is where the role expands beyond a single project. A practice architect doesn’t just design systems, they design how systems get designed. They establish frameworks, decision records, and architectural practices that teams can use without waiting for top-down approval. Their deliverables aren’t just diagrams, but processes: decision logs, architecture review boards, documentation standards, and communication channels that make architectural intent stick beyond a single sprint.

They drive consistency across multiple teams, creating the connective tissue that enables autonomy without chaos. Common patterns, shared libraries, CI/CD foundations, and standard observability practices are all part of their toolkit. The practice architect creates the scaffolding that keeps an engineering organization from splintering apart.

The Work: Business, Technical, and Solution Specific

A solid architect has to be fluent in three languages: business, technical, and solution. Each speaks a different truth.

Business Work

Here’s where the architect translates intent into implications. Understanding the revenue model, customer expectations, regulatory constraints, and delivery pressure is part of the job. You turn “real-time analytics” into “streaming data ingestion with 99.9% uptime and a sub-500ms query response.” That translation is the work.

Technical Work

This is where you live in the code and infrastructure. Choosing frameworks, defining service boundaries, selecting protocols, and ensuring scalability and resiliency are the bread and butter. You make sure the system can evolve. This is where non-functional requirements stop being buzzwords and start being design constraints you engineer around.

Solution Work

This is synthesis. You take the business intent and technical constraints, and build something that delivers both. It’s part art, part engineering, and entirely iterative. It’s also where you wrestle with the mess; the legacy code, the politics, and the reality that greenfield never stays green for long. Good solution architecture isn’t about the cleanest design, it’s about the right design for right now.

Working Across the Organizational Web

The real power of an architect isn’t in drawing boxes, it’s in connecting people who live in different ones. Architecture is as much a social system as it is a technical one.

A capable architect spends just as much time aligning teams as writing code or reviewing it. They operate in the seams of the organization: the handoff between Product and Engineering, where DevOps meets Security, where Marketing’s promises collide with technical reality, and where Support feels the fallout from design shortcuts. This bridging work is fundamental. It’s not optional, and it’s not “soft skills.” It’s the backbone of how complex systems actually get delivered.

Every senior technical role shares this responsibility. Staff, Principal, or Architect it doesn’t matter what your title says, your success depends on your ability to bridge silos. As a Principal Engineer, you’re often spanning horizontally across product lines and technical domains, ensuring cohesion between efforts. As an Architect, you’re bridging vertically and horizontally while translating business strategy into technical execution and back again. Both require deep context, credibility, and communication.

You talk to Product about tradeoffs and timelines. To Technical Product Owners about system boundaries and risk mitigation. To Developer Relations about usability and external developer experience. To Marketing about aligning technical capabilities with how the product is positioned. To Support and Operations about observability, resilience, and making sure the system doesn’t implode at 2AM. You’re the connective tissue between worlds that don’t naturally interact.

That’s what makes this level of engineering different. It’s not about writing more code. It’s about broadening your influence about seeing how design decisions ripple through people, processes, and systems. You learn to speak the language of each group without losing your technical grounding. Product won’t listen if you don’t understand deadlines. Engineers won’t respect you if you can’t code. Executives won’t care if you can’t tie architecture to revenue or risk. You have to earn trust in every direction.

The Reality Check

A software architect is part diplomat, part engineer, part historian. You carry institutional memory, technical rationale, and enough humility to admit when a “perfect design” isn’t the right one today. You have to stay close enough to the implementation to feel its pain, but far enough from the weeds to see the horizon. The balance is strategy informed by code, and code informed by strategy.

To be truly effective as an architect you don’t live in an ivory tower. You live in the intersection where technical ambition meets human limitation. And if you’re doing it right, you build systems that last just long enough for someone else to rewrite them better. 🤙🏻