Documentation Standards for Series B and Beyond

The Day the Slack Scroll Stopped Working

Every engineering organization has a moment when tribal knowledge stops scaling. For a 12-person team, it might be when the founder finally admits they can no longer remember why that one service talks to that other service over a queue nobody else can name. For a 40-person org closing Series B, it's usually more dramatic — an outage where three engineers spend four hours tracing a request path that should take ten minutes, only to discover the answer lived in a DM from 2022.

Documentation stops being a nice-to-have somewhere between the seed round and Series B. It becomes load-bearing. The question is whether the standards you adopt are intentional or improvised under pressure. The companies that get this right treat their documentation system the same way they treat their code review process: as a piece of infrastructure that needs ownership, conventions, and automation.

This is a working guide for engineering leaders who've inherited (or are about to inherit) a documentation mess, and want to fix it without slowing the team down.

What Changes at Series B

Series A teams can survive on README files, Notion pages, and the institutional memory of their first ten engineers. Series B is where that breaks, and it breaks for predictable reasons.

Headcount crosses the Dunbar threshold

Once you cross roughly 50 engineers, no single person knows every system that ships to production. The original architects are now reviewing PRs for code they wrote three years ago, in a language that's been partially rewritten since. New hires onboard against documentation that was either never written or last updated when the company was pre-revenue. The CTO's calendar becomes a documentation hotline.

Architecture gets heavier

Pre-Series-B systems often run on a handful of services and a monolith. By Series B, you're typically looking at 30–80 services, multiple data stores, async pipelines, third-party APIs with their own versioning cadence, and an internal platform layer that some team owns and nobody else fully understands. The mental model that fit in one engineer's head now needs to be externalized.

Compliance shows up

SOC 2, ISO 27001, HIPAA, GDPR — pick your acronym. Almost all of them ask for documentation of systems, processes, and controls. A security audit will surface every gap in your runbooks, access policies, and architecture diagrams. This is rarely the reason companies build documentation standards, but it's the deadline that forces the work to land.

Velocity starts dropping in ways leadership can measure

Time-to-onboard for new engineers stretches from days to weeks. Incident MTTR creeps up. The same architectural questions get asked in standup, in 1:1s, in Slack threads, and in retrospectives. Each repetition is a small tax that compounds into a real cost.

The Four Documents You Actually Need

You don't need a documentation platform with 47 templates. You need four core documents, well-defined, kept current, and discoverable. Everything else is secondary.

1. The System Architecture Overview

This is the single most important document in a Series B engineering org. It answers three questions:

• What systems exist?
• How do they talk to each other?
• Why is the system shaped this way?

The shape of this document matters less than its existence and accuracy. Common formats:

• A C4-style diagram (Context, Container, Component, Code) maintained in a tool like Structurizr, IcePanel, or draw.io
• A markdown document with embedded Mermaid diagrams, version-controlled alongside code
• A Notion or Confluence page linked from the repo root

The best version is whichever one your engineers will keep updated. A beautiful diagram that drifts out of date is worse than a rough diagram that's regenerated every quarter.

The "why" part is the part teams skip. The current architecture is the residue of a hundred decisions — why this database, why this queue, why this boundary. Capture the non-obvious decisions in ADRs (Architecture Decision Records), one per decision, with context, options considered, and tradeoffs accepted.

2. The Service README Template

Every service, library, or major internal tool should have a README that follows a consistent template. Not a freeform README — a template. Here's the minimum that pays back the time spent writing it:

# Service Name

## What it does
One paragraph. The job this service exists to do, in plain language.

## Who owns it
Team name, Slack channel, on-call rotation link.

## How to run it locally
The exact commands. Not "see the wiki." The commands.

## How to deploy it
The CI pipeline, the manual override path, the rollback procedure.

## Key dependencies
Upstream services it calls, downstream services that call it,
external APIs with version pinning.

## Observability
Where logs live, what dashboards to look at, what alerts fire.

## Known sharp edges
The things that bite people. The environment variables that must
be set. The state that must be cleaned before redeploy. The race
condition that only happens under load.

The "known sharp edges" section is the one engineers love most. It's the closest thing to a senior engineer sitting next to a junior engineer saying "don't do that."

3. The Runbook

Runbooks are operational documentation — what to do when X is on fire. They live next to the service or in the on-call tooling (PagerDuty, Opsgenie, incident.io). Every alert should link to a runbook. Every runbook should have:

• Symptoms: what the user sees, what the alert says, what the dashboard shows
• Likely causes: ordered by probability based on history
• First checks: the three or four commands or dashboard links a responder opens first
• Escalation path: who to page if the first checks don't resolve it
• Recent incidents: links to the last few postmortems for this system

Runbooks are not architecture documents. Keep them short, current, and operationally focused. A runbook that's six months stale is worse than no runbook, because responders will trust it and waste time.

4. The Onboarding Guide

The onboarding guide is the document that compounds in value. Every week it's good, the company saves hours of new-hire context-loading. Every week it's bad, the company pays for it in slow ramp-up times and frustrated engineers.

A good onboarding guide is opinionated and chronological:

• Day 1: accounts, laptop setup, access requests
• Week 1: the codebase tour, the architecture overview read, the first PR
• Month 1: the systems they own, the people who own what they don't

The best onboarding guides are written by engineers who recently went through onboarding. They're specific, slightly opinionated, and full of "I wish someone had told me this on day one" energy.

The Standards That Make Documentation Stick

Most documentation efforts fail not because of bad writing, but because of missing standards. Here are the five that matter.

Single source of truth, by category

Pick one place for each kind of document and forbid the others:

Document type	Location
Architecture	Version-controlled markdown in a central repo
Service READMEs	Co-located in the service repo
Runbooks	Co-located in the service repo, linked from alerting
Process and policy docs	Notion or Confluence
ADRs	Version-controlled markdown in a central repo

The mistake is letting architecture docs live in Notion and process docs live in READMEs. Engineers don't know where to look, so they ask in Slack, so the answer lives in Slack, so it gets lost.

Docs as code, where it counts

Anything architectural — diagrams, ADRs, system overviews — should be in version control. The reasons are the same as for code: review process, history, blame, branchability. A diagram in Notion that nobody updates is a diagram you can't trust.

You don't need to put everything in version control. Process docs and onboarding guides benefit from the rich editing of Notion or Confluence. But anything that describes how the system works should be reviewable, diffable, and tied to a commit.

Ownership, not authorship

Every document needs an owning team, not an author. Authorship implies the document was written once. Ownership implies it gets maintained. Put owner teams in the document header. When ownership changes (team renames, reorgs), update the docs in the same PR.

The freshness signal

A document with no indication of when it was last verified is a document nobody trusts. Add one of two things to every doc:

• A "Last verified" date with the name of the person who verified it
• A "Last updated automatically" timestamp tied to the doc generation pipeline

The first is better for documents that need human judgment to verify. The second is better for documents that can be generated from code.

Doc review in PRs

If docs live in version control, they go through the same review process as code. Two effects: documentation gets the same quality bar as code, and code changes that affect architecture get caught forcing doc updates.

The exact mechanism varies. Some teams require README updates in any PR that changes service behavior. Some teams have a separate docs reviewer. Some teams use automation that flags when a PR changes a service without updating its README. The principle is the same: docs are part of the change, not an afterthought.

The Anti-Patterns That Will Sink You

Knowing what to avoid is half the battle.

The doc freeze

The temptation is to declare a documentation week, have everyone write everything, and ship a complete documentation set. This produces a beautifully complete set of documents that are six months out of date within a quarter, because the people who wrote them moved on to other work and nobody owns the maintenance.

Don't do documentation drives. Do documentation habits. A small, consistent practice beats a large, one-time effort.

The docs as a separate team's problem

Some companies try to solve documentation by hiring technical writers or a developer relations team. This works for marketing-facing docs and API references. It does not work for internal architecture documentation, because the people with the knowledge to write it are engineers, and engineers will not write it if writing it is not part of their workflow.

Internal architecture docs are an engineering problem. Solve them with engineering process.

The wiki graveyard

A Confluence or Notion space with 4,000 pages, half of them stale, navigable only by people who already know what's there. This is the default state of unstructured documentation tools in mid-size companies. The cure is structure: templates, owners, freshness signals, and the willingness to delete what's no longer accurate.

Documentation theater

The worst anti-pattern is documentation that exists to satisfy an audit rather than to help engineers. A SOC 2 control document that says "we have a process for X" with no actual process behind it is a liability, not an asset. It will pass the audit and fail the incident.

How DocPilot Fits Into This

The hardest part of documentation standards at Series B is keeping the four core documents current as the system evolves. A service gets a new dependency; its README doesn't get updated. A team splits a service into two; the architecture diagram doesn't get redrawn. A runbook links to a dashboard that was renamed; nobody notices until an incident.

DocPilot generates the four core documents — READMEs, architecture overviews, setup guides, API references — directly from your codebase, and keeps them in sync via GitHub webhooks. When a PR merges, the docs update. When a service changes shape, the architecture diagram regenerates. Engineers don't have to remember to maintain the docs because the docs are derived from the code.

This doesn't replace the human judgment parts — the "known sharp edges," the ADRs, the onboarding guide's opinionated tour. Those still need engineers to write them. But it eliminates the 80% of documentation work that is mechanical and gets skipped when it's manual.

Series B is where documentation stops being a founder's hobby and starts being a system. Build it like one.