The Async-First Fallacy: Why Documentation Alone Won't Save Your Remote Team

[cto_michelle]

I’m going to say something controversial: the async-first movement is overselling documentation as a silver bullet.

I lead a 120-person remote-first engineering organization. We’ve invested heavily in documentation infrastructure. We have comprehensive wikis, detailed ADRs, extensive runbooks. And yes, it helps. But if I’m being honest about what actually makes our distributed team effective? Documentation is necessary but not sufficient.

Let me explain the gap between async-first theory and distributed team reality.

Three Documentation Anti-Patterns I See Everywhere

1. Write-Only Culture

Documentation gets created but never consumed. Engineers dutifully write ADRs because the process requires it. Those ADRs get committed to Git and never read again. New engineers ask questions in Slack instead of searching docs because nobody trusts that docs are current or comprehensive.

It’s documentation theater—going through the motions without the substance.

2. Zombie Wikis

Comprehensive documentation that’s outdated within months. We’ve all seen this: a beautiful wiki with hundreds of pages, organized into categories, searchable and well-intentioned. But 40% of it describes systems that no longer exist, processes that changed, or decisions that got reversed.

Stale documentation is worse than no documentation. It actively misleads.

3. Documentation Instead of Conversation

The most insidious pattern: using “we should document that” as a way to avoid having difficult conversations. Architecture decisions that need real-time debate get deferred to “write an RFC.” Strategic disagreements get turned into competing documentation. Important decisions get slower, not faster.

The Alternative: Executable Documentation

Here’s what I’m increasingly convinced of: the best documentation is code that documents itself.

• Type systems are contracts that can’t go stale
• Tests are specifications that break when behavior changes
• Infrastructure-as-code is architecture documentation that stays current by definition
• Automated diagram generation from actual systems beats hand-drawn diagrams

Manual documentation should be reserved for things code can’t express: context, tradeoffs, strategic intent.

The Real Cost Analysis

Let’s be honest about what comprehensive documentation actually costs:

Manual Doc Maintenance:

• Initial creation: 10% of engineering capacity
• Keeping current: another 5-10% ongoing
• Cultural overhead: endless debates about what needs documenting

Tooling Investment:

• Automated testing: pays for itself in bug prevention
• Type systems: pay for themselves in refactoring safety
• Observability: pays for itself in incident reduction
• Self-documenting architecture: pays for itself in cognitive load reduction

The ROI math isn’t close. We’re over-investing in manual prose and under-investing in executable contracts.

When to Document vs When to Talk

The async-first ideology treats synchronous communication as a failure. But some things are genuinely better resolved in real-time:

• Strategic disagreements that need rapid iteration
• Architectural debates with multiple valid options
• Crisis response and incident management
• Onboarding conversations that surface unknown unknowns

Documentation should capture decisions and context after the conversation, not replace the conversation.

My Proposal: Tiered Documentation Strategy

Not all documentation has the same lifecycle:

Tier 1 - Code as Documentation (perpetual)

• Tests, types, contracts
• Infrastructure-as-code
• API schemas
• Automated architecture diagrams

Tier 2 - Architectural Context (years)

• ADRs for major decisions
• System design overviews
• Technology strategy

Tier 3 - Operational Knowledge (months)

• Runbooks
• Onboarding guides
• Process documentation

Tier 4 - Ephemeral (weeks)

• Meeting notes
• Decision logs
• Status updates

Different tiers deserve different maintenance investments.

The Uncomfortable Question

Maybe we’re documenting too much of the wrong things. Maybe the async-first movement has overcorrected from “just talk to people” to “just read the docs” without acknowledging that some knowledge transfer is fundamentally conversational.

Are we documenting too much of the wrong things and not enough of the right things?

What if the answer isn’t more comprehensive documentation but more intelligent choices about what to document, what to automate, and when to just have a conversation?

---

Looking forward to getting challenged on this.

[vp_eng_keisha]

Challenge accepted!

You’re absolutely right about zombie wikis—they’re a real problem. But I think the root cause isn’t documentation itself, it’s lack of ownership and hygiene.

We had the same issue. Beautiful wiki, comprehensive content, and within months nobody trusted it. The breakthrough came when we treated documentation like we treat code: it needs owners, it needs maintenance, and it needs periodic cleanup.

What worked for us: quarterly documentation review as a team ritual.

We blocked off 4 hours, pulled up the wiki, and went through it together. Three questions for every page:

1. Is this still accurate?
2. Is this still relevant?
3. If neither, should we update it or delete it?

In our first review session, we deleted 30% of the wiki. It felt liberating. Stale docs were creating cognitive overhead—people had to evaluate trustworthiness before they could extract value.

The key insight: documentation hygiene is like code hygiene. You wouldn’t let dead code sit in your codebase forever. You refactor, you deprecate, you remove. Why treat docs differently?

Here’s my counter-proposal to your tiered strategy: what if we treated docs like features?

• Docs should have owners (DRIs who maintain them)
• Docs should have expiration dates (unless explicitly marked perpetual)
• Docs should be deprecated when they no longer serve their users
• Doc health should be a team metric (% of docs updated in last 6 months)

I love your executable documentation point for operational knowledge. Tests as specs, IaC as architecture docs—that’s brilliant for things that change frequently.

But for strategic context and architectural decisions, I still believe in manual documentation with active maintenance. The question isn’t manual vs automated—it’s owned vs orphaned.

[eng_director_luis]

Your tiered documentation strategy resonates strongly. Different docs definitely need different maintenance models.

In fintech, we’re forced to maintain certain documentation for compliance—there’s no “executable” alternative when auditors want to see written procedures. But that constraint actually helped us develop a hybrid approach that works well.

Our tiered model:

Tier 1 - Compliance/Regulatory (permanent, manual)

• Required by law/regulation
• Professional documentation, formal review cycles
• Expensive but non-negotiable

Tier 2 - Architecture Decisions (years, manual)

• ADRs for major choices
• System design context
• Updated rarely, referenced often

Tier 3 - Operational (months, hybrid)

• Runbooks that start as manual docs
• Gradually automated where possible
• Runbook execution teaches us what to automate

Tier 4 - Ephemeral (weeks, automated)

• Incident logs generated from systems
• Meeting notes from recordings
• Status dashboards auto-generated

The insight we’ve had: architecture decisions document once, reference forever. The ADR we wrote three years ago explaining why we chose Postgres over MongoDB? Still valuable. Gets referenced in onboarding, in new feature discussions, in vendor evaluations.

But operational runbooks? Those need to be living documents OR executable scripts. We’ve found success with a pattern: start with manual runbook, run it 5-10 times, then invest in automating it.

Question: Which documentation categories are genuinely worth manual effort vs pushing toward automation? I suspect the line is clearer than we think.

[alex_infrastructure]

The executable documentation angle speaks to me as an infrastructure engineer, so let me share what we’ve actually implemented.

Docs-as-code with automated validation:

We treat documentation like we treat infrastructure: version controlled, CI/CD validated, automated where possible.

• Link rot detection: CI fails if docs link to pages that 404
• Last-updated warnings: Bot adds banner to docs not touched in 6+ months
• Orphan page cleanup: Weekly report of docs with zero views in 90 days
• Automated architecture diagrams: Generated from Terraform/K8s configs

Integration with monitoring:

When an incident happens, our runbook system auto-suggests updates based on:

• Commands actually run during incident resolution
• New failure modes discovered
• Recovery time vs documented estimates

The runbook becomes a living document that learns from incidents.

That said, I’m skeptical of pure automation. Some context is inherently human. The “why we chose X” question needs prose, not just code.

My question: Has anyone successfully auto-generated architecture documentation from code/infrastructure?

We’ve tried:

• Terraform → diagram (works okay for infrastructure)
• Code → dependency graphs (too noisy to be useful)
• OpenAPI → API docs (great for reference, terrible for learning)

The generated docs are comprehensive but lack narrative. They answer “what” but not “why” or “when.”

Maybe that’s the distinction: executable documentation for reference, manual documentation for learning.