Documentation Is Still Developer Experience's Weakest Link in 2026—What Would Actually Make Docs Not Suck?

General
1

Despite billions in DevEx investment, thousands of new tools, and endless Slack threads about “developer productivity,” there’s one thing that still consistently sucks across nearly every engineering org I’ve worked with: documentation.

I’m not talking about the aspirational state where we all pretend docs are great. I’m talking about the reality where new engineers spend their first week asking “where is this documented?” and the answer is usually “it’s not” or “check Slack from 2023” or my personal favorite: “just ask Sarah, she knows.”

The Business Case Nobody Wants to Hear

Here’s what makes this particularly painful from a product perspective:

  • Projects with high-quality documentation see 63% faster onboarding times (source)
  • 26% of developer productivity loss comes from gathering project context (source)
  • Yet most engineering orgs treat docs as a “nice to have” that gets punted every sprint

The math doesn’t math. We’re literally choosing to handicap our teams because documentation feels like unglamorous work.

What’s Actually Broken

After talking to dozens of engineering leaders, the same patterns emerge:

1. The Fragmentation Problem

  • Critical information scattered across Confluence, Notion, Google Docs, READMEs, Slack, and “John’s brain”
  • No single source of truth
  • Search is useless because context lives in 6 different systems

2. The Staleness Death Spiral

  • Docs reference tools that were deprecated 2 years ago
  • Nobody knows who owns updates
  • Code changes, docs don’t
  • Engineers stop trusting docs, so they don’t read OR write them

3. The Ownership Vacuum

  • “Everyone’s responsible” = nobody’s responsible
  • Documentation seen as punishment, not core work
  • No time allocated in sprints
  • No metrics tracking documentation quality

What’s Changed in 2026 (That Makes This Problem Worse)

The AI revolution has simultaneously made this better AND worse:

Better: AI tools like Copilot can now read and interpret your docs to provide contextual help. Interactive API explorers with “Try It” features (Fern, Mintlify) are becoming table stakes. Docs-as-code workflows mean version control and reviews are possible. (source)

Worse: 84% of devs use AI tools daily, but we’re generating code faster than we can document it. The verification and documentation debt is piling up faster than ever. (source)

Beyond “Just Write Better Docs”

That advice is useless. Of course we should write better docs. The question is what systemic changes would actually move the needle?

Here’s a framework I’ve been thinking about:

  1. Discoverability – Can developers find the information they need in under 2 minutes?
  2. Accuracy – Is the information current and correct?
  3. Completeness – Does it answer the question, or just point to 3 other docs?
  4. Usability – Can someone take action based on this information?

Most docs fail on at least 2 of these dimensions.

The Questions I’m Wrestling With

  • Should we treat docs like production code (CI/CD, ownership, SLOs)?
  • Do we need dedicated technical writers, or is that admission of failure?
  • Can AI actually solve this (chatbots trained on internal docs), or is that a bandaid?
  • How do you make documentation a first-class citizen without killing velocity?

What Would Actually Work?

I’m convinced the answer isn’t just tooling. It’s culture + process + tooling. But I’m curious what’s actually working for teams in 2026:

  • What documentation investments have paid off for you?
  • What experiments have spectacularly failed?
  • How do you measure documentation quality?
  • Who owns docs in your org?

Because if we can’t solve this, we’re going to keep losing 26% of our productivity to context gathering while wondering why AI tools aren’t making us ship faster.

What would it take to make docs not suck at your company?

2

This hits SO close to home. :sweat_smile:

At my failed startup, documentation was always the “we’ll do it after launch” task. Spoiler: we never did it after launch because there was always a “real” feature to build. Then we hired our third engineer and onboarding took 3 weeks instead of 3 days because nothing was written down—not the auth flow, not the deployment process, not even which Slack channels to join.

That’s when I learned docs aren’t a nice-to-have. They’re a leading indicator of whether your team can scale.

What Actually Worked: Treat Docs Like a Design System

At my current company (design systems team), we started treating documentation the same way we treat our component library:

  • Modular and versioned – Each component has its own docs page that versions with the code
  • Clear ownership – Every docs page has an assigned owner who gets notified on staleness
  • Review process – Docs changes go through the same PR review as code changes
  • Usage analytics – We track which docs pages get viewed, which get bounced, which lead to support questions

The result? Our component adoption rate went from ~40% to ~85% after we added interactive playgrounds where engineers could see and modify component code in real-time.

The Human Element Nobody Talks About

Here’s the uncomfortable part: our best documentation came from pairing new hires with technical writers during their first two weeks. We literally followed them around (virtually), documented every question they asked, and turned those questions into docs.

It was expensive. It was slow. It worked.

Why? Because experienced engineers have the curse of knowledge—we forget what it’s like not to know things. New hires are the perfect litmus test for what’s missing.

Visual Thinking > Text Walls

One thing I learned from design: show, don’t just tell.

  • Screenshots age badly (they’re wrong the moment the UI changes)
  • But architecture diagrams with tools like Excalidraw or Mermaid stay relevant for years
  • Code playgrounds (CodePen, JSFiddle embedded) let people experiment without risk
  • Video walkthroughs for complex flows (we use Loom, keep them under 3 minutes)

We found that a 90-second Loom showing “how to set up your local environment” reduced onboarding support questions by ~60%.

The Cultural Truth Bomb

Here’s the thing nobody wants to admit: documentation quality reflects team culture.

If your team doesn’t value writing things down, no tool will fix it. Not Notion, not Confluence, not some AI chatbot. The tool choice is like 20% of the problem. The other 80% is whether people believe documentation is “real work.”

At my startup, the CEO never read docs and always just asked us directly. So the team learned that docs didn’t matter. It was a death spiral.

At my current company, our CTO references the docs in every code review and will literally reject PRs that don’t update relevant documentation. Guess what? Our docs are pretty good now.

My Question Back to You

How do you balance comprehensive documentation vs “just enough to get started”?

Because I’ve seen teams fall into two traps:

  1. Too comprehensive – 500 pages nobody reads because finding anything is impossible
  2. Too minimal – “See README” which is 3 lines and assumes you already know everything

I’m starting to think the answer is progressive disclosure (design term)—start with the simplest happy path, then link to deeper dives for advanced users. But curious what’s worked for others here.

Also: David, your framework (Discoverability, Accuracy, Completeness, Usability) is :fire:. I’m stealing that for our next docs audit.

3

David, Maya—this thread is gold. The “documentation as reflection of culture” point especially resonates.

In financial services, we have an interesting constraint: compliance requires documentation. Every API, every data flow, every security control needs to be documented for auditors. You’d think this would mean we have great docs, right?

Wrong.

We have compliance documentation (which satisfies auditors but is useless for developers) and then a separate world of actual useful developer documentation (which is often missing).

What Actually Worked: The Ownership + Measurement Model

Here’s what we implemented across 40+ engineers that moved the needle:

1. Documentation Champions (10% Time Allocation)

Each squad has a designated “documentation champion” who gets 10% of their sprint capacity explicitly allocated to docs work. Not volunteer work. Not “do it in your spare time.” Actual story points.

This person isn’t a technical writer—they’re a senior engineer who:

  • Reviews docs for accuracy during PRs
  • Runs quarterly docs audits
  • Onboards the docs-shadow pairing Maya mentioned
  • Tracks documentation metrics

2. Time-to-First-PR as Our North Star

We started tracking “time to first meaningful PR” for every new hire. Broke it down into phases:

  • Environment setup: 4 hours → 45 minutes (after better docs)
  • Understanding architecture: 3 days → 1 day
  • First code contribution: 2 weeks → 5 days

Documentation impact became impossible to ignore when we could show the executive team “better docs = 60% faster onboarding = $X saved in engineering time.”

3. AI-Powered Internal Q&A Bot

We fed our internal documentation (wikis, READMEs, runbooks) into a Claude-powered Slack bot. New hires can ask questions like “How do I deploy to staging?” and get answers with source citations.

Results: Bot handles ~70% of basic onboarding questions. The other 30% that it can’t answer? Those become backlog items to add to docs.

It’s not a replacement for good docs—it’s a forcing function to identify gaps.

4. Docs-as-Code Changed Everything

Moving from Confluence to Markdown files in the repo cut staleness by ~60%. Why?

  • Code review catches outdated docs (they’re right next to the code)
  • Git history shows when docs were last updated
  • Engineers are comfortable with Markdown + PRs
  • We can run automated checks (broken links, missing sections)

We use a simple CI check: if you modify code in /src/payments/ but don’t touch docs in /docs/payments/, the build warns you.

5. The Maintenance Problem: Automated Staleness Detection

Every quarter, we run a script that:

  • Identifies docs that reference deprecated packages
  • Flags docs that haven’t been updated in 12+ months
  • Checks for broken links or missing images
  • Creates GitHub issues for the owning team

Cultural enforcement: stale docs count against team’s quality metrics in quarterly reviews.

The Thing That Failed Spectacularly

Initially, we tried to have engineers write everything themselves. Quality was terrible. Half-finished thoughts, assumed context, inconsistent structure.

What worked instead: Writers shadow engineers, engineers review for accuracy.

We hired 2 technical writers (expensive, but ROI is clear). They:

  • Sit in on architectural discussions
  • Pair with engineers to document complex systems
  • Interview new hires to find gaps
  • Maintain docs quality standards

Engineers still write the initial rough docs, but writers make them actually useful.

Question for the Group

How do you handle documentation for legacy systems where the original authors are long gone?

We have services that are 8+ years old with zero original team members left. Docs are sparse or wrong. Re-documenting from scratch is expensive. Leaving it undocumented is risky.

Current approach: prioritize based on change frequency + business criticality. But curious if others have solved this better.

Also, Maya’s point about progressive disclosure is spot-on. We’re experimenting with a “Quick Start” + “Deep Dive” structure for each service. Quick Start is <5 minutes to get running. Deep Dive is for when you need to actually change something.

Still iterating, but initial feedback is positive.

4

Luis, that 10% time allocation for documentation champions is brilliant. Stealing that immediately.

From a CTO perspective, I’ll be blunt: documentation is infrastructure, not a nice-to-have. You wouldn’t skip monitoring or CI/CD. Why would you skip the knowledge layer that lets your team actually function?

But here’s the uncomfortable truth—most engineering orgs under-invest in documentation because it’s hard to quantify the ROI. Until you start measuring it.

How We Made the Investment Case

When I joined as CTO 3 years ago, our docs situation was a disaster. Our board wanted to scale from 50 to 150 engineers in 18 months. I told them we’d fail if we didn’t fix documentation first.

Here’s how I got budget approval for $100K/year in documentation investment:

The Measurement Framework

We tracked three metrics and tied them directly to business impact:

1. Support Ticket Volume

  • Internal Slack questions tagged #how-do-i
  • BEFORE: ~200/week
  • AFTER (12 months): ~120/week
  • Impact: Senior engineers spending 40% less time on “how does X work?” questions

2. Onboarding Time-to-Productivity

  • Days until new hire’s first merged PR
  • BEFORE: 18 days average
  • AFTER: 11 days average
  • Impact: $50K saved per new hire in lost productivity

3. Cross-Team Questions

  • How often teams need to ask other teams “how does your service work?”
  • BEFORE: Constant interruptions, context switching nightmare
  • AFTER: 40% reduction in synchronous handoffs
  • Impact: Measurable improvement in team focus time

We presented these numbers quarterly. The board stopped questioning the documentation budget after Q2.

The Platform Play: Developer Portal

Fragmentation was killing us. Docs in Confluence, APIs in Swagger, runbooks in Notion, architecture diagrams in Google Slides.

We built an internal developer portal using Backstage:

  • Service catalog with ownership, docs, APIs, runbooks in one place
  • Software templates for spinning up new services (with docs scaffolding)
  • Tech radar showing approved vs deprecated technologies
  • Integrated search across all documentation sources

Result: Developers now have a single starting point. Discoverability problem largely solved.

AI Integration: The 70% Solution

We embedded an AI chatbot (trained on our internal documentation) directly into Slack and the developer portal.

What it handles well (70% of questions):

  • “How do I deploy to production?”
  • “What’s the API endpoint for user authentication?”
  • “Where are the runbooks for the payment service?”

What it fails at (30% of questions):

  • Complex architecture decisions
  • “Why did we choose X over Y?”
  • Tribal knowledge that was never documented

The key insight: AI amplifies your documentation quality. If your docs are bad, the AI makes that very obvious very quickly.

We now treat AI failures as documentation gaps. Every question the bot can’t answer creates a backlog ticket.

What Failed: Asking Engineers to Write Everything

Same as Luis—quality was terrible when we expected engineers to write comprehensive documentation.

What worked: Hired 2 FTE technical writers plus contracted a docs agency for big projects.

Writers don’t write in isolation. They:

  • Shadow engineers during design reviews
  • Interview SMEs (subject matter experts)
  • Observe new hire onboarding
  • Draft docs, engineers review for technical accuracy

Engineers still own docs, but writers make them usable.

ROI calculation: 2 writers at $180K/year total. They enable 50 engineers to save ~5 hours/week on context gathering and questions. That’s 250 hours/week = $2.5M/year in engineering time saved (at $200/hour loaded cost).

The investment paid for itself 25x over.

Strategic View: Docs as a Scalability Indicator

Here’s something I track that most CTOs don’t: documentation quality is a leading indicator of organizational scalability.

If your team can’t document how things work, you can’t:

  • Onboard new engineers efficiently
  • Enable other teams to self-serve
  • Scale without creating bottlenecks (everyone asking the same 5 people)
  • Maintain systems when people leave

I’ve seen this pattern repeatedly: companies that scale successfully invest in documentation early. Companies that struggle either didn’t invest or invested too late.

The Challenge: Maintaining Quality at 3x Scale

Luis asked about legacy systems. I’ll add another question: How do you maintain documentation quality while scaling 3x?

We’re going from 50 to 150 engineers. Our docs-as-code + ownership model works now, but I’m concerned about:

  • Consistency across 20+ teams with different docs styles
  • Keeping the developer portal maintained as service count grows
  • Ensuring new teams adopt documentation best practices
  • Preventing fragmentation as teams start using their own tools

Current approach: Documentation standards in our engineering handbook + required docs review in promotion rubrics (you can’t get to senior+ without demonstrating docs leadership).

But I’m curious—for folks who’ve scaled beyond 200 engineers, what broke and how did you fix it?

David’s framework is excellent. I’d add one more dimension:

  • Maintainability – Can this documentation be kept current without heroic effort?

Because the best-written doc in the world is useless 6 months later if it’s wrong.

5

This conversation is exactly what I needed today. Michelle’s point about documentation as infrastructure resonates deeply—especially as someone trying to scale an EdTech startup where we literally sell learning products but struggle to document our own systems. The irony is not lost on me.

The Inclusion Lens: Documentation Levels the Playing Field

Here’s an angle I don’t see discussed enough: good documentation is an equity issue.

When knowledge is primarily transferred through:

  • Hallway conversations
  • Lunch discussions
  • “Just ask me” culture
  • Tribal knowledge in senior engineers’ heads

You systematically disadvantage:

  • Remote/distributed team members who aren’t in the office
  • Async workers (parents, folks in different timezones, neurodiverse colleagues who work off-hours)
  • Junior engineers who don’t feel comfortable constantly asking questions
  • Underrepresented folks who already face “prove yourself” pressure and don’t want to appear unknowledgeable

Strong documentation culture isn’t just about efficiency—it’s about creating an environment where everyone has equal access to context.

The New Hire Audit: Our Documentation Backlog Source

We do something similar to Luis’s approach, but with a twist:

Every new hire’s first 30 days = documentation audit

We track every single question they ask:

  • In 1:1s with their manager
  • In team Slack channels
  • During pairing sessions
  • In code reviews

At the end of 30 days, we review the list and ask: “Which of these questions should have been answerable via documentation?”

That becomes our docs backlog for the quarter.

Results:

  • New hires feel heard (“my confusion is creating value!”)
  • We document the actual questions people have, not what we think they need
  • Senior engineers can’t hand-wave with “everyone knows that”—clearly they don’t

Ownership Model: CODEOWNERS for Docs

We use GitHub’s CODEOWNERS feature for both code AND documentation.

Every repo has:

  • /src/ with code owners
  • /docs/ with documentation owners (often the same people, but explicit)

PR rules:

  • Code changes without corresponding docs updates get flagged in CI
  • Can’t merge to main without docs owner approval
  • Docs staleness (>6 months since update) shows up in team quality dashboards

This makes documentation ownership as clear as code ownership.

The Experiment: Interactive Onboarding Paths

We built a “choose your own adventure” onboarding docs system:

Day 1 question: What role are you?

  • Frontend Engineer → sees FE-specific setup, tools, patterns
  • Backend Engineer → sees BE stack, deployment, database docs
  • ML Engineer → sees model deployment, data pipelines, notebooks

Day 5 question: What are you working on first?

  • User authentication → links to auth service docs, security guidelines
  • Data pipeline → links to data platform, ETL processes
  • API development → links to API standards, testing guides

Instead of one massive onboarding doc that everyone skims, new hires get a personalized path. Completion rate went from ~30% to ~85%.

We use Mintlify for this—their conditional content and interactive playground features made it possible.

The Tool That Changed Everything: Mintlify for API Docs

We switched from Swagger UI to Mintlify for our API documentation. The difference is night and day:

What Mintlify gives us:

  • Interactive “Try It” console – developers can make real API calls from the docs
  • Automatic code samples in 7 languages (curl, Python, JavaScript, etc.)
  • Docs-as-code – markdown files in our repo, versioned with the API
  • AI-powered search that actually understands intent
  • Embedded videos and diagrams that don’t break the flow

Impact: API adoption by internal teams went up 3x. External partner integration time dropped by 40%.

The interactive playground specifically was huge—engineers could test endpoints, see real responses, debug auth issues, all without leaving the docs.

Measurement: Tying Docs to DORA Metrics

This might be controversial, but we started correlating documentation quality with DORA metrics (deployment frequency, lead time, change failure rate, MTTR).

What we found:

  • Teams with comprehensive runbooks had 50% lower MTTR (mean time to recovery)
  • Teams with up-to-date architecture docs had 30% shorter change lead time
  • Teams with good onboarding docs had lower change failure rates (new people didn’t break things as often)

Documentation became a leading indicator of team performance. When docs quality drops, team metrics follow within 1-2 quarters.

We now include “documentation health” in our quarterly engineering reviews alongside velocity and quality metrics.

The Cultural Shift: Quarterly “Docs Days”

Every quarter, we do a “Docs Day”—the entire engineering team pauses feature work for one day to:

  1. Update stale documentation
  2. Write missing runbooks
  3. Record Loom videos for complex processes
  4. Delete outdated docs (just as important!)
  5. Review new hire feedback and address gaps

Initially there was resistance (“we’re losing a sprint day!”). But after seeing onboarding time drop and support questions decrease, teams now request these days.

We make it fun: best docs improvement wins a prize, we share “most creative diagram” awards, and leadership participates (I documented our incident response process last quarter).

The Hard Truth: Top-Down Cultural Commitment

Maya nailed it earlier: if leadership doesn’t value docs, the team won’t either.

In my org:

  • Our CEO references the docs in all-hands and publicly thanks teams for good documentation
  • I reject PRs that don’t update relevant docs (yes, as VP Eng I still review critical PRs)
  • Documentation contributions count toward promotion (explicitly in our engineering ladder)
  • Poor documentation is treated like tech debt—gets prioritized, not ignored

This sends a clear signal: documentation isn’t extra work, it’s the work.

My Burning Question

How do you make documentation a first-class citizen in sprint planning without teams feeling like velocity is suffering?

Because I hear this all the time: “If we spend time on docs, we ship fewer features.”

My counterargument: “You ship features once, but people read docs hundreds of times. The ROI is obvious.”

But I’m curious how others frame this conversation, especially when leadership is skeptical.

Michelle, your ROI calculation ($2.5M in saved time for $180K investment) is exactly the kind of framing that works with boards. I’m stealing that for our next planning cycle.

And Luis, the automated staleness detection is genius. Do you have a script or tool you’d be willing to share? We’ve been doing this manually and it’s painful.

Fantastic thread, David. This is going in our leadership reading list.