Building a Team Handbook (Your Team's

A team handbook is the written answer to every question people ask more than once. Its value is not completeness — it is that decisions stay decided and knowledge stops living in one person's head. Handbooks fail when someone tries to write the whole thing in a week, and they succeed when they grow one entry at a time from actual questions.

The rule that builds a good handbook is simple: when you answer the same question twice, write it down the second time.

What a Handbook Replaces

Three recurring costs disappear when a handbook exists: repeated answers, key-person dependency, and decisions being remade.

Answering the same question repeatedly

How do we handle expenses. What is our deploy process. When do we escalate to the on-call engineer. Who approves a discount.

Each of these gets asked several times a year, usually of the same person, who answers slightly differently each time. Writing it once costs ten minutes and saves the same conversation indefinitely.

Knowledge held in one person's head

Every team has someone who knows how something works because they built it or have been there longest.

That concentration is fine until they are on leave, or they leave. The handbook is insurance against a risk most teams do not price until it materialises.

Decisions relitigated every few months

Without a record of why something was decided, the same debate recurs — usually raised by someone who was not there the first time and has no way of knowing it was settled.

Recording the decision and its reasoning ends this. "We considered that in March and chose otherwise for these reasons" is a two-minute conversation instead of a two-hour one.

What Goes In It

Four sections. Most teams need less than they expect.

Section Contains Examples How we work Norms and expectations Working hours and time zones, response time expectations by channel, meeting norms, how we make decisions, how we give feedback

How we do things Repeatable processes Deploy process, incident response, expense claims, hiring steps, onboarding checklist, how work enters the backlog What we decided Dated decision records Why we chose this stack, why we do not do X, pricing decisions, tooling choices — each with reasoning Reference Things people look up Who owns what, key contacts, glossary of internal terms, links to systems, escalation paths

What does not belong: anything that changes weekly, anything better held in the project tool, and aspirational statements about values nobody acts on.

What to Write First

Priority order, based on what each entry saves.

Priority Write this Because 1 The question you have answered most times this month Immediate, measurable saving 2 Anything only one person knows Removes a key-person risk 3 The onboarding path for a new joiner Every hire uses it; new joiners find its gaps 4 Response time expectations by channel Prevents most async friction 5 How decisions get made and by whom Prevents stalled and relitigated decisions 6 Your two or three most-run processes Deploy, incident, intake 7 Decision records, from now onward Cheap going forward, expensive retrospectively

Do not attempt to write history. Start recording decisions from today.

Writing Entries People Actually Use

Lead with the answer, record why, and mark who owns it and when it was last true.

Answer the question, then explain

First line: the answer. Then the context.

People arrive at a handbook entry with a specific question. Making them read three paragraphs of background before reaching it is how documentation acquires a reputation for being unhelpful. "Expenses over $200 need approval from your manager before you spend" — then the rest.

Record the reasoning, not just the rule

A rule without a reason cannot be evaluated later. When circumstances change, nobody knows whether the rule still applies.

"We deploy on Tuesdays and Wednesdays because Thursday and Friday deploys caused weekend incidents twice in 2025" tells a future reader when the rule can be revisited. "We deploy Tuesday and Wednesday" does not.

Date it and name an owner

Every entry: last reviewed date, and one named owner.

Undated documentation is untrustworthy because readers cannot tell whether it is current. An entry dated eighteen months ago at least tells you to check. Keeping the handbook as docs linked to the relevant projects, rather than in a separate system nobody opens, means people encounter entries where the work happens.

Keeping It From Rotting

Write when a question repeats, delete without sentiment, and check ownership quarterly.

Update it when you answer a question twice

This is the whole maintenance strategy. No documentation sprints, no scheduled writing time.

The second time you answer something, write the answer down and send the link. The handbook grows exactly as fast as it is needed, and every entry is proven useful before it exists.

Delete aggressively

Out-of-date documentation is worse than none, because people follow it.

When something is no longer true, delete it rather than marking it deprecated. A handbook that only contains current information is trusted; one where readers must assess each entry's freshness is not.

Review ownership quarterly

People change roles and leave. Fifteen minutes each quarter checking that every entry still has a live owner.

Ownerless entries are the ones that rot, because nobody feels responsible for noticing they are wrong.

Common Handbook Mistakes

Three failures: writing everything at once, documenting aspiration, and nobody owning it.

Writing it all at once

A team decides to build a handbook, blocks two days, writes forty pages, and never touches it again. Six months later most of it is wrong.

Grow it from real questions. A handbook of twelve genuinely useful entries beats forty pages nobody trusts.

Aspirational rather than actual

Documenting how you wish you worked rather than how you actually work.

New joiners follow the written process, discover it is not what happens, and conclude the handbook is unreliable. Write what is true, including the parts that are not ideal — an honest entry saying "this process is awkward, we know" is more useful than a tidy fiction.

Nobody owns it

A handbook without a named overall owner drifts, then rots, then gets replaced by a new handbook in a different tool eighteen months later.

One person owns the whole thing — not writing everything, but ensuring entries have owners and the quarterly review happens.