We Tried "Document Everything" and Created a Graveyard of Stale Docs—Better Approaches?

General
1

Two years ago our design team had almost nothing documented. Designers kept institutional knowledge in their heads. New hires struggled. Product partners couldn’t find design decisions. Engineers built things that violated our design system because they didn’t know it existed.

So we went all-in on documentation. “Document everything” became the mantra. Six months later, we had… a graveyard of stale documentation that nobody trusted.

The Documentation Explosion Problem

We documented:

  • Design system components (in Figma)
  • Design principles (in Notion)
  • User research findings (in Dovetail)
  • Design process guides (in Confluence)
  • Project handoff docs (in Notion)
  • Design review templates (in Google Docs)

Sounds great, right? Except:

  1. Docs went out of sync immediately. We’d update a Figma component but forget to update the Notion doc explaining when to use it. Now we had two conflicting sources of truth.

  2. Nobody knew what was current. Search would return three different documents about navigation patterns. Which one was right? The most recent? The longest? The one with the most links to it? No way to tell.

  3. Documentation became a chore, not a value-add. Designers resented spending time updating docs. It felt like homework, not real work. So docs rotted further.

  4. The search problem got worse, not better. More docs meant more noise. Finding the right answer took longer than before we documented anything.

What We’re Trying Now: Living Documentation

Current experiment (six months in, seems to be working better):

Every doc must have an owner and an expiry date. When you create a doc in Notion, you assign an owner and set a “Review by” date (usually 3-6 months out). When that date hits, owner gets pinged: “Is this still accurate? If yes, extend the review date. If no, update it or archive it.”

This forces us to confront stale docs rather than letting them accumulate. We’ve archived ~40% of our original documentation. Turns out most of it wasn’t needed.

Quarterly documentation review sprints. One week per quarter, design team does no new work. We spend the week:

  • Reviewing all docs due for review
  • Updating outdated screenshots and examples
  • Consolidating duplicate docs
  • Actually reading each other’s docs to see if they make sense

This sounds like overhead, but it’s better than continuous low-grade doc debt that slowly makes all documentation untrustworthy.

“If it’s not in Figma or Notion, it doesn’t exist” rule. No more design decisions in Slack threads, email, or meeting notes. If a decision happens, it must be added to either:

  • Figma (for component/visual decisions)
  • Notion (for process/strategy/research decisions)

This is hard to enforce and feels rigid, but it prevents the “I’m sure we decided this six months ago but I can’t find where” problem.

Single source of truth, published everywhere. Our design system source of truth is Figma. But we generate docs from Figma and publish to Notion (for context and usage guidelines) and Storybook (for engineers).

When we update Figma, we have a checklist: “Did you update Notion? Did you update Storybook?” Not perfect, but better than maintaining three separate docs.

What Still Doesn’t Work

Keeping docs current without making it a full-time job. Our quarterly review sprints help, but docs still drift between sprints. I don’t know how to make documentation feel like part of the work rather than extra work on top of the work.

Knowing when something needs documentation. Not everything needs a doc. Some decisions are small and reversible. But we don’t have good intuition for “this needs to be written down” vs “this is fine to keep informal.” So we either over-document (more graveyard docs) or under-document (critical context lost).

Automated approaches. I keep hearing about tools that auto-generate docs from code or design files. Has anyone actually made this work for design documentation? What tools? What’s realistic vs hype?

Making docs searchable across tools. We have docs in Figma, Notion, Confluence, Dovetail, and Storybook. Search within each tool is fine, but cross-tool search is terrible. Do you consolidate everything into one tool, or is there a better way?

What I’m Curious About

For those who’ve figured out sustainable documentation practices:

  1. How do you keep docs current without quarterly doc sprints or constant maintenance overhead?
  2. What’s your mental model for “this decision needs documentation” vs “this is fine to leave informal”?
  3. Any tools or automation that actually reduces doc burden rather than adding to it?
  4. How do you handle the tension between comprehensive documentation (everything is written down) and useful documentation (easy to find what you need)?

I suspect the answer isn’t “better discipline” but rather different systems or tooling, but I’m open to being wrong.

2

“Docs are code” is one of the most powerful mindset shifts we’ve made. When you treat documentation with the same rigor as production code—versioning, review, ownership, testing—the quality and maintainability improve dramatically.

Here’s what that means in practice:

Documentation lives in the codebase. We use docs-as-code: Markdown files in the same repo as the code, reviewed in the same PRs, deployed to the same CI/CD pipeline. When you change an API, you update the API doc in the same commit. The doc review is part of code review.

This solves the sync problem. Docs can’t get out of date without code also being wrong, because they’re coupled. If someone ships a feature without updating the docs, it fails code review just like missing tests would.

Generated docs over manual docs. Anything that can be auto-generated should be:

  • API docs: Generated from OpenAPI specs or code annotations
  • Database schema: Generated from migrations
  • Component API surface: Generated from TypeScript interfaces
  • Architecture diagrams: Generated from actual infrastructure code (Terraform, K8s manifests)

We still write manual docs for “why” and “how to use,” but the “what exists” layer is always generated and therefore always accurate.

Archival policy: Docs have three states:

  • Current: Maintained, shows up in search, supported
  • Archived: Read-only, searchable but marked as old, not maintained
  • Deleted: Gone. We’re aggressive about deleting. If a doc hasn’t been read in 12 months (we track page views), it gets deleted, not archived. You can recover from git history if really needed, but we don’t keep zombie docs around.

Single source of truth principle. Never duplicate information. If you need the same info in multiple places, use links or includes. For example, our “how to deploy” doc lives in one place but is included/linked from multiple contexts (onboarding, runbooks, architecture docs).

Your quarterly doc sprints are good, but I’d argue they’re a symptom that your docs live outside your workflow. If docs are reviewed with every code change, you don’t need dedicated doc sprints.

The cultural shift required: Getting engineers to treat docs as seriously as code took about a year. We had to:

  • Make doc updates block PR approval (literally, CI checks that certain docs are updated)
  • Celebrate good documentation in the same way we celebrate good code
  • Measure doc quality (page views, time-to-onboard, doc coverage metrics)
  • Have technical writers embedded in eng teams, not a separate docs team

It’s worth it. Our onboarding time dropped from 6 weeks to 2 weeks, and our “where is this documented?” Slack questions dropped by ~70%.

3

Your owner + expiry date model is smart. We do something similar but tier documentation by expected shelf-life:

Tier 1: Evergreen (2+ year lifespan)

  • Company values and mission
  • Core architectural principles
  • High-level system architecture

Review: Annually. Owner: CTO or VP Eng.

Tier 2: Stable (6-12 month lifespan)

  • Design system guidelines
  • Development processes (code review, deploy process)
  • Team structure and ownership

Review: Quarterly. Owner: Team leads.

Tier 3: Active (1-3 month lifespan)

  • Current project specs
  • Sprint plans
  • Active incident postmortems

Review: Monthly or when project closes. Owner: Project lead.

Tier 4: Transient (1-2 week lifespan)

  • Daily standups
  • WIP design explorations
  • Draft RFCs

Review: Never—these are meant to be temporary. Auto-archive after 30 days if not converted to a higher tier.

The key insight: Stop treating all documentation the same. A company values doc should be rock-solid and change rarely. A project spec should be living and update frequently. When you mix these together, you either over-maintain the evergreen stuff (waste of time) or under-maintain the active stuff (docs go stale).

Office hours for documentation questions. We hold “docs office hours” twice a week—30-minute drop-in sessions where anyone can ask “where should I document this?” or “I can’t find the doc for X, does it exist?”

This surfaces two things: (1) What’s missing that people need, and (2) What exists but is un-findable (which means it’s effectively missing).

Tool automation we use:

  • Notion API scripts: We have a cron job that checks all Notion docs for last-updated date. If a doc hasn’t been updated in 6 months, it pings the owner in Slack.
  • Confluence to Notion migration: We killed Confluence entirely. One less tool to search.
  • Figma plugin: We built a simple Figma plugin that pulls component descriptions from Figma and generates Markdown files that we commit to our docs repo. Not perfect, but better than manually copy-pasting.

Answer to “when does this need docs?”: Our rule of thumb:

  • If >3 people need to know it: Document it.
  • If you’ll need to remember it in 3 months: Document it.
  • If it affects user experience or production systems: Document it.
  • If it’s reversible and scoped to one person’s work: Probably doesn’t need docs.

The third person asking the same question is the trigger. First time? Answer in Slack. Second time? Maybe write it down. Third time? Definitely write it down and update search keywords so people can find it.

4

The tension between comprehensive and useful documentation is so real. In product, we’ve struggled with the same thing—product specs that are exhaustive but no one reads because they’re 20 pages long.

Our current approach: Living PRDs with progressive disclosure.

The PRD has three sections that serve different audiences:

Executive Summary (1 page)

  • What are we building and why? (2-3 sentences)
  • Success metrics (3-5 bullets)
  • Launch date and key milestones
  • Owners (PM, Eng lead, Design lead)

This is the “need to know” layer for stakeholders, execs, adjacent teams.

User Stories & Acceptance Criteria (2-3 pages)

  • User flows with wireframes
  • Edge cases and error states
  • What’s in scope, what’s explicitly out of scope

This is for engineers and designers building the thing.

Research & Context (appendix, as long as needed)

  • User research findings
  • Competitive analysis
  • Options we considered and why we chose this approach
  • Open questions and known risks

This is for future you when someone asks “why did we do it this way?” six months later.

The key: Each section stands alone. You can read just the exec summary and get value. You can read exec summary + user stories and start building. You only dive into the appendix if you need deep context.

Keeping it current: The PRD is “alive” until launch, then it gets frozen and marked as “shipped.” Post-launch, we don’t update the PRD—we write a separate “What we learned” retrospective that links back to the original PRD.

This prevents the “which version is right?” problem. Pre-launch docs are living. Post-launch docs are historical records.

Balance comprehensive vs useful: We err toward useful. If a section of the PRD hasn’t been referenced in a month, we delete it. If someone asks a question that isn’t covered, we add it.

Documentation should be demand-driven, not supply-driven. Write docs when people need them, not preemptively because you think they might need them someday.

That said, there’s one category where we do comprehensive documentation: Decisions and tradeoffs.

Any time we choose Option A over Option B, we write down:

  • What options we considered
  • Why we chose this one
  • What we’re giving up
  • What would make us reconsider

This prevents re-litigating decisions and helps new team members understand the reasoning. It’s worth being comprehensive here because the alternative is people second-guessing decisions they weren’t part of.

Cross-tool search: We haven’t solved this perfectly, but we use Notion as the “hub” with links to everything else (Figma designs, Jira tickets, GitHub PRs, Dovetail research). The Notion doc is the table of contents; the actual artifacts live in their native tools.

Still not ideal, but better than expecting one tool to do everything.

5

The “documentation as chore” problem is cultural, not just process. If writing docs feels like overhead, people won’t do it—or they’ll do it badly just to check a box.

Here’s what made documentation feel like value-add for us:

Make it easier to document than not to document. We built Slack bots and CLI tools that make documentation one command away:

  • /doc-decision Slack command: Opens a template in Notion, pre-filled with context from the Slack thread. You add 2-3 sentences of “what we decided and why,” hit submit, done. Takes 30 seconds.

  • git doc CLI command: After you merge a PR, running git doc opens a template to document what you just shipped. It pre-fills from your commit messages and PR description. You edit for clarity, commit, push.

  • Figma plugin: When you mark a component as “Ready for dev” in Figma, it prompts you for a 1-sentence usage guideline. That gets auto-added to your component library docs.

The key: Reduce friction to near-zero. If writing a doc requires opening a new tool, creating a new page, copying a template, filling out 10 fields… people won’t do it. If it’s one command and 30 seconds, they will.

Celebrate good documentation as a first-class contribution. In our monthly all-hands, we highlight “Doc of the Month”—someone who wrote exceptionally clear or useful documentation. We give out the same recognition as “Engineer of the Month” or “Designer of the Month.”

We also track documentation contributions in performance reviews. Writing the architecture doc that onboards new engineers faster counts as much as writing the code.

Templates with examples. Every doc template includes an example of a well-done version. Don’t just say “Describe the problem”—show what a good problem description looks like.

We found that people’s biggest barrier wasn’t laziness, it was not knowing what “good documentation” looked like. Examples help calibrate quality.

Make docs discoverable by default. Any new doc created in Notion automatically gets posted to #team-updates Slack channel with a summary. This serves two purposes:

  1. People discover docs they didn’t know they needed
  2. Doc authors get immediate feedback (“This is helpful!” or “Wait, I think this is out of date with X”)

Discoverability is half the battle. Great docs that no one knows exist are useless.

Answer to your question about tension between comprehensive and useful: I think you actually want different things for different audiences.

  • Comprehensive for archeology: When you need to understand “why did we do this?” you want comprehensive—all the context, all the tradeoffs.
  • Useful for daily work: When you’re trying to get something done, you want concise—just the facts, no fluff.

So write both, but structure them with progressive disclosure (like David mentioned). Summary up top, details below. Let people choose their depth.

One more thing: Have a documentation champion. Not a full-time role, but someone who cares about docs and is empowered to nag people, improve templates, run doc review sessions, etc. Without a champion, documentation is everyone’s responsibility, which means it’s no one’s responsibility.