Skip to main content

Writing as Infrastructure: Why Async-First is a Technical Decision

culture operations writing

Most companies say they value documentation. Then they schedule a meeting to discuss it.

I have become increasingly uninterested in organizations that run on oral tradition.

We made a different choice. Writing is not a byproduct of our work — it is the medium of our work. ADR-0003 didn’t just change how we communicate. It changed what counts as having communicated.

The decision

Our architectural decision record for async-first communication is specific about the hierarchy:

Normal: Documentation → Email → Chat
Urgent: Chat → Phone → Whatever works
Emergency: Phone immediately, document after

Before scheduling a meeting, we ask: could this be a document, a Slack thread, or a recorded walkthrough? If so, do that instead. When a meeting does happen, it must have an agenda, an owner, and produce written notes.

This is not remote-work accommodation. It’s a technical decision about institutional memory.

Why writing is technical

Writing forces clarity of thought. Vague ideas become obvious on paper. A decision that seems obvious in a meeting often turns out to have assumptions nobody examined. Writing surfaces those assumptions because the author has to make them explicit.

Written artifacts are searchable, linkable, and permanent. A verbal decision in a meeting is forgotten by Thursday. A documented decision with context, options, and consequences is available to everyone who joins the team after the decision was made.

This matters more than most organizations realize. The cost of undocumented decisions is not immediately visible. It shows up six months later, when a new team member makes a contradictory choice in good faith because the original rationale was never written down.

What it looks like

We have five architectural decision records. Each follows the same structure: status, context, options considered (with pros and cons), the decision, and consequences (positive, negative, and neutral).

ADR-0004 (Terraform) doesn’t just say “we use Terraform.” It explains that CDK was a reasonable alternative but adds an abstraction layer and is AWS-locked. That Pulumi’s community is smaller and defaults to a SaaS for state management. That Terraform was chosen for the largest ecosystem, the most transferable skillset, and a plan/apply workflow that fits PR-based review. That the BSL license change is a risk, with OpenTofu as a fallback.

Someone reading that document — a year from now, having never met the person who wrote it — can understand not just what was decided, but why, what was rejected, and what the trade-offs are. They can disagree with the decision. They can’t accidentally re-litigate it without knowing they’re doing so.

The handbook

The handbook has 41 markdown files across company, operations, engineering, product, finance, and reference sections. Its stated success metric is “reduced ambiguity.”

Every document is tested against a question: could a capable employee make a correct decision using only this document? If not, the document is incomplete.

This means documents include not just procedures but:

  • Default behavior — what to do if unsure
  • Allowed discretion — what the reader can decide independently
  • Escalation triggers — when to stop and ask
  • Non-goals — what this document does not cover

The handbook CLAUDE.md file (instructions for Claude Code working in the handbook repo) says: “If a document does not reduce cognitive load or decision friction, it is incomplete.”

CLAUDE.md as architecture documentation

Every repository has a CLAUDE.md file. These started as instructions for Claude Code, but they became something more useful: living architecture documentation that’s actually maintained because it has a daily consumer.

CollectionChecker’s CLAUDE.md describes the API service layer pattern, the theme system, the auth context, the localStorage tracking, the storage buckets, the edge functions, the environment variables, and the common gotchas. w3f1nd’s CLAUDE.md does the same for its stack.

These files stay current because they’re used by a tool that fails visibly when they’re wrong. Traditional architecture docs decay because nobody reads them. CLAUDE.md files don’t decay because Claude reads them on every interaction.

The compound effect

The compounding is real and observable.

Every new app integrates faster because the auth patterns are documented — not just “how to set up Clerk” but how the JWT template works, why the JWKS cache expires after 24 hours, what ensure_profile does and why it uses INSERT ON CONFLICT.

Every technical decision is cheaper because the prior decisions and their rationale are available. When we considered how to handle auth for Steleology (Astro SSR, not a React SPA), the auth library’s CLAUDE.md already documented the Astro middleware pattern. No meeting. No Slack thread. Read the doc, adapt the pattern.

Every CLAUDE.md file makes the next CLAUDE.md file easier to write because the conventions are established.

The cost

Writing takes time. A thorough ADR takes an hour or more. CLAUDE.md files need updating when the architecture changes. The handbook needs periodic review to ensure it still matches reality.

Some conversations are better synchronous. Sensitive feedback, creative brainstorming, and relationship building don’t translate well to async. We don’t pretend otherwise. The ADR explicitly calls these out as cases where sync is appropriate.

Writing requires writing skill. Poor writing creates confusion at scale — a vague document read by twenty people generates twenty different interpretations. This means writing quality is a hiring criterion, not an optional nice-to-have.

The alternative

The alternative is an organization that runs on oral tradition. Decisions live in the heads of the people who made them. Architecture is understood by the person who built it and whoever happened to be nearby when they explained it.

Oral tradition works while the team is small and everyone is in the same room. It stops working the moment someone takes vacation, changes teams, or leaves. At that point, the organization discovers that its institutional memory walked out the door.

Writing prevents this. Not by being more pleasant or more collaborative or more inclusive — those are side effects. Writing prevents it because writing is durable and searchable in ways that speech is not.

The investment is real. The alternative is more expensive.