"Documentation as Code" Exists, But 70% of Platform Teams Have Stale Docs—Is This a Tooling Problem or a Culture Problem?

General
1

I’ve been thinking about this a lot lately as we scale our Series B SaaS company. We’ve adopted all the “docs as code” best practices—documentation lives in Git, goes through PR reviews, has automated deployments, version control, the works. We have the tooling: GitBook for external docs, Backstage for internal developer portal, Notion for product specs. We have the process: documentation PRs required for major features.

Yet our platform documentation is still falling behind.

The Documentation Paradox

Here’s what’s puzzling: the tooling exists, the processes exist, but 70% of platform teams still report outdated documentation (source). This isn’t for lack of trying. Most engineering organizations I talk to have invested significantly in docs infrastructure.

At my company, we’re seeing the symptoms:

  • Customer support escalations because docs are unclear or outdated
  • New engineers take 6 weeks to be productive (should be 4)
  • Product launches delayed because integration guides aren’t ready
  • Sales losing deals because prospects can’t figure out our API

The business impact is real. Each week of documentation debt compounds—support load increases, customer trust erodes, competitive advantage diminishes.

Two Competing Hypotheses

I’ve been wrestling with whether this is fundamentally a tooling problem or a culture problem:

The Tooling Hypothesis

Maybe our current tools don’t integrate well enough. Engineers face too much friction updating docs. The workflows between code and documentation aren’t seamless. We need better automation, smarter integrations, AI-powered doc generation, unified platforms that make updating docs as easy as shipping code.

The Culture Hypothesis

Or maybe it doesn’t matter what tools we have—if documentation isn’t valued and incentivized, it won’t happen. Engineers are rational actors who optimize for what gets measured and rewarded. We promote people for shipping features fast, not for maintaining comprehensive docs. Of course docs fall behind.

The Framework I’m Using

As a product leader, I think about this through the lens of Documentation as Code: Building Developer Portals:

Inputs: Engineering time, tooling investment, cross-functional contribution
Process: Writing, reviewing, maintaining, versioning documentation
Output: Up-to-date, accurate, useful documentation
Outcome: Faster onboarding, reduced support load, better developer experience

Where’s the breakdown? Are we failing at inputs (not enough time allocated)? Process (tools too cumbersome)? Or is there a fundamental incentive misalignment that no tool can fix?

What I’ve Tried

We’ve experimented with:

  • Better tools: Migrated from Confluence to GitBook (marginal improvement)
  • Process mandates: Required doc PRs for features (compliance ~60%, often superficial)
  • Documentation sprints: Dedicated time to pay down doc debt (temporary bump, then decay)

Nothing has fundamentally shifted the trajectory. The pattern is always the same: initial enthusiasm, gradual decline, eventual staleness.

The Question I’m Asking

For those of you who’ve actually solved this—not just talked about solving it—which lever mattered most?

Did you find a tool that genuinely changed the game? Did you make cultural/organizational changes that stuck? Did you crack the incentive structure?

And more importantly: how do you sustain it? Because I can get docs to 80% coverage in a sprint. Keeping them there for 6 months is the real challenge.

I suspect the answer is “both tools and culture,” but I’m looking for specifics. What worked in your organization? What failed? Where should we invest next?

Cross-posted from a conversation I’ve been having with eng leadership. Curious to hear product, engineering, and design perspectives on this.

Sources:

2

David, this resonates deeply with challenges we’ve faced in financial services. After trying multiple documentation tools over the years, I’ve come to believe: it’s culture, but culture requires systems to change it.

Tools Are Amplifiers, Not Replacements

Here’s what I’ve learned managing 40+ engineers across distributed teams: engineering tools are multipliers. In a healthy culture, great tools accelerate excellence. In an unhealthy culture, they accelerate chaos.

We tried Confluence. Then GitBook. Then Backstage. Each time we thought “this tool will fix it.” Each time, initial adoption was high, then gradual decay. The tools weren’t the problem—our lack of accountability was.

What Actually Worked: Tying Docs to Performance

The breakthrough came when we made documentation a first-class criterion in performance reviews and promotion decisions, particularly for senior+ engineers. Not as a checkbox, but as a genuine evaluation dimension.

Specifically:

  • Required documentation PRs for every feature PR (can be in same commit or separate, but must exist)
  • Both code AND docs reviewed together—reviewers explicitly asked “how would a new engineer understand this in 6 months?”
  • Made documentation contributions visible in quarterly reviews
  • For Staff+ promotions, demonstrated ability to explain complex systems clearly became a hard requirement

The Results

This wasn’t about better tools—we’re still using the same Backstage setup. But documentation quality improved dramatically because engineers knew it mattered for their career progression.

When an engineer submits a PR now, they know their reviewer will check:

  1. Does the code work?
  2. Is it tested?
  3. Is it documented?

All three are weighted equally in the review. This cultural shift came from leadership (VP Eng and CTO) explicitly stating that documentation quality affects promotion velocity.

The Broader Point

Platform Engineering Isn’t a Tooling Problem. It’s a Culture Problem, as the research shows. You can have the most sophisticated docs-as-code setup, but if engineers are promoted purely for feature velocity, they’ll rationally deprioritize docs.

My recommendation: before investing in another tool, answer these questions:

  1. Is documentation quality discussed in performance reviews?
  2. Can an engineer get promoted to senior+ without demonstrating documentation excellence?
  3. Do code reviews explicitly evaluate documentation?

If the answers are no, no, and no—start there. Systems shape culture, and culture determines whether tools succeed or fail.

3

This hits close to home—I’ve lived both sides of this (design systems lead now, failed startup founder before). I think it’s both tooling and culture, but here’s the key: documentation is communication, not code.

We’re Optimizing for the Wrong Thing

Luis makes a great point about culture and incentives. But I want to push back on the framing a bit: we treat docs like code when they’re actually more like design. They need user empathy, not just technical accuracy.

At my failed startup, we had beautiful technical documentation. Every API endpoint documented. Every component had prop types. Every function had JSDoc comments. Engineers loved our docs.

Customers were still confused.

Why? Because our documentation was optimized for the writer (engineers), not the reader (users with different mental models).

The Documentation User Experience Problem

When we talk about “docs as code,” we inherit a developer-centric worldview:

  • Code comments document HOW something works (implementation details)
  • Platform docs need to document WHY and WHEN to use it (user intent)

These are fundamentally different communication goals.

Example from design systems: I can document that a Button component accepts —that’s the “code” part. But what users actually need is: “Use primary buttons for the main action on a page (usually only one). Use secondary for supporting actions. Use tertiary for low-emphasis actions.”

The first is technical. The second is design thinking applied to documentation.

Tools Don’t Solve Communication Problems

This is where I partly disagree with the “better tools” hypothesis. GitBook, Mintlify, Backstage—they’re all optimized for engineers to write documentation efficiently. They’re Git-based, Markdown-driven, version-controlled.

But they create friction for:

  • Product managers who need to document feature rationale
  • Designers who need to explain component usage guidelines
  • Support teams who need to clarify common confusions
  • Customers who just want to know “how do I accomplish X?”

At my current company, the design team can’t update component docs in GitBook because it requires Git knowledge they don’t have. So they Slack screenshots instead. Fragmentation wins again.

The Real Question

Are we optimizing docs for writers or readers?

Building a culture of documentation means asking: who is the user of this documentation? What’s their goal? What’s their existing mental model?

Before we argue tools vs. culture, maybe we need to step back and ask: what problem are we actually solving? If it’s “make it easier for engineers to write docs,” docs-as-code is great. If it’s “help users accomplish their goals,” we might need a different approach entirely.

Just my 2 cents from the design side of the table.

4

David, you’ve identified the core tension. Luis is right about culture and systems. Maya’s right about user empathy. But let me add the leadership perspective: you can’t culture-hack your way around bad incentives.

Culture Requires Intentional Design

At my EdTech startup, we had the “docs matter” conversation for 6 months. Town halls, slack messages, team retros. Everyone nodded. Nothing changed.

Why? Because while we were saying docs matter, our promotion criteria and performance reviews didn’t include documentation quality. Engineers are smart—they optimize for what actually affects their career, not what leadership says in meetings.

What We Changed (Specifically)

Here’s what actually worked for us:

1. Updated Engineering Competency Matrix

  • Added “Documentation Quality” as an explicit criterion for Senior Engineer and above
  • Defined it clearly: “Can explain complex systems to varied audiences with appropriate technical depth”
  • Made it required, not nice-to-have

2. Quarterly Documentation OKRs

  • Every quarter, we set team-level documentation goals
  • Example: “Increase API documentation coverage from 62% to 85%”
  • Tracked it in sprint planning, reviewed in retros
  • Gave it equal visibility with feature OKRs in exec reviews

3. Public Recognition

  • Monthly “Doc Hero” shoutout in all-hands for engineers who improved existing docs
  • Created Slack channel (#docs-wins) where people shared doc improvements
  • Made documentation contributions high-status work, not grunt work

The Results (6 Months Later)

  • API documentation coverage: 45% → 82%
  • Support tickets citing “unclear docs”: down 40%
  • Engineer survey “I feel supported by internal docs”: 3.2 → 4.1 (out of 5)
  • Time-to-first-commit for new engineers: 8 days → 5 days

The culture changed because the incentive structure changed.

You Need Leadership Commitment

Here’s the uncomfortable truth: if you’re not willing to delay a promotion because someone’s documentation is poor, you don’t actually think docs matter. Engineers will figure that out immediately.

We had a senior engineer up for Staff promotion—excellent code, shipped critical features, but consistently wrote minimal docs. Feedback in multiple reviews: “improve documentation.” He didn’t. We delayed his promotion by one cycle.

Word spread fast. Documentation quality improved across the team.

The Answer to Your Question

You asked which lever mattered most—tools or culture. My answer: culture, but culture is downstream of incentives, and incentives are a leadership choice.

Tools can reduce friction. But if the underlying incentive structure says “ship fast, docs don’t matter for your career,” no tool will fix that.

Start with:

  1. Add documentation to competency matrices
  2. Review it in performance conversations
  3. Recognize and reward it publicly
  4. Be willing to make hard calls when someone’s docs are consistently poor

The tools become effective once the culture values documentation. Not before.

5

Excellent thread. Luis, Keisha, Maya—you’re all touching on different facets of the same problem. But I want to reframe this entirely: this is an ownership problem masquerading as a tools/culture debate.

The Ownership Vacuum

When I started leading our cloud migration initiative, I asked a simple question: “Who owns documentation quality at this company?”

I got 5 different answers:

  • Engineering: “We write it, but Product should define what needs documenting”
  • Product: “We’re not technical enough to write developer docs”
  • DevRel: “We can improve it, but we don’t have repository access”
  • Support: “We know where docs are wrong from customer questions, but we can’t fix them”
  • Platform team: “We provide the tooling, not the content”

Result: Nobody owns it. So docs decay.

Documentation Without Ownership Is Just Technical Debt

We wouldn’t say “everyone owns the authentication system.” We assign a DRI (Directly Responsible Individual) or a team. We have on-call rotations. We have escalation paths.

Why don’t we do this for documentation?

What We Implemented: Documentation DRIs

Here’s our structure now:

Quarterly Documentation DRI Rotation

  • Each product area has a Documentation DRI (rotated every quarter)
  • DRI is a senior+ engineer who spends ~15-20% time on docs
  • Not their whole job (that kills career growth), but a meaningful rotation

DRI Responsibilities:

  1. Audit existing docs for accuracy in their product area
  2. Prioritize documentation debt
  3. Review all doc PRs for their domain
  4. Quarterly report to leadership: “State of Docs” for their area
  5. Authority to block PRs if documentation is incomplete

Why Rotation?

  • Spreads knowledge across team
  • Prevents burnout (it’s temporary)
  • Builds empathy for documentation consumers
  • Creates accountability without creating a separate “docs team”

The Controversial Part

We give Documentation DRIs real authority: they can block a PR from merging if documentation is missing or poor. This was controversial initially (“slows down shipping!”), but it forced the conversation.

Now, engineers proactively ask the DRI for doc review before submitting PRs. Because nobody wants to be blocked at merge time.

The Framework: Docs as a Product

Treat documentation like you treat product features:

  • Product Manager: Who defines what docs are needed? (often the DRI)
  • Roadmap: What’s the priority order for documentation work?
  • Metrics: How do you measure doc quality? (coverage %, support tickets, user satisfaction)
  • Retrospectives: What’s working? What’s not?

David, you asked about sustaining 80% coverage over 6 months. Our answer: ownership with accountability. When there’s a name attached to doc quality (not just a team), problems get fixed.

The Measurement Side

We track:

  • Documentation coverage per product area (automated)
  • Support tickets citing unclear/missing docs
  • Time-to-productivity for new engineers (leading indicator of doc quality)
  • Quarterly “Internal Doc NPS” survey

These metrics are reviewed in exec meetings alongside feature velocity. What gets measured at the exec level gets prioritized at the team level.

To Answer Your Question Directly

Tools: Keep your current setup (GitBook, Backstage, whatever). Don’t migrate.
Culture: Important, but culture follows structure.
Ownership: This is the missing piece.

Before you invest in better tools or more culture-building, answer this: Who owns documentation quality? And I want a name, not a team. If you can’t answer that, start there.

P.S. One metric that changed our perspective: we started tracking “documentation-related incidents”—outages or errors caused by unclear/missing runbooks. When we showed the exec team that 18% of incidents had a documentation component, investment in docs suddenly became a reliability issue, not a nice-to-have.