New series: what assistive tech really hears on your checkout page. Start with part one →
Shipwright
Home
Career Sep 17, 2026 2 min read

Writing Documentation That Survives a Reorg

Sam Whitfield

Sam Whitfield

Engineering manager and recovering QA lead.…

Share
Cover illustration for the article Writing Documentation That Survives a Reorg

Templates and habits that keep docs useful when the team that wrote them moves on. The hardest problems on an engineering team are rarely technical. This post is about the habits and small agreements that let a group of people ship good work without burning out.

Why this matters

We changed one thing at a time and wrote down why. That record turned out to be the most useful part, because six months later nobody remembered the original problem.

decision-template.md
# Decision: <short title>

**Date:** 2024-05-01
**Status:** accepted
**Owners:** @platform-team

## Context
What problem are we solving, and why now?

## Decision
What did we choose?

## Consequences
What gets easier, what gets harder, and when do we revisit this?

What we changed

Reviews got faster once we agreed on what they are for: catching bugs and sharing knowledge. Style debates moved to the linter, and architecture debates moved to a short design note before any code was written.

  • Agree on what code review is for.
  • Write decisions down where people will find them.
  • Automate style arguments away.
  • Pair new people with a named mentor.

How it went

Remote work made all of this more deliberate. Decisions that used to happen in a hallway now happen in writing, which is slower in the moment and much faster for everyone who joins later.

As always, the examples are simplified to fit on a page. The production version has more error handling and logging, but the shape of the code is the same.

Questions, corrections, and war stories are welcome in the comments. Several of our best follow-up posts started as a reader pointing out something we had missed.

Before you ship this

A template nobody fills in is worse than no template. Keep it to four headings and make the first one about the problem, not the solution.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler, Refactoring, 1999

Wrapping up

If you try this on your own project, start with one page or one service rather than the whole codebase. A small experiment gives you real numbers to argue with, and it is easy to roll back if the idea does not fit.

Sam Whitfield

Sam Whitfield

Author

Engineering manager and recovering QA lead. Sam writes about testing, code review, and building teams that ship calmly.

Related Posts

Comments 5

Ravi Shankar

This finally clicked for me after reading the docs three times.

Amara Nwosu

Our accessibility audit flagged exactly this last month. I wish I had read this first.

Ben Carter

Bookmarked. The code sample alone saved me an afternoon.

Sofia Rossi

Tried it on a side project over the weekend and it worked first time, which never happens.

Elias Lindqvist Member

The quote in the middle is doing a lot of work here, and it earns it.

Leave a comment

Your email will not be published. Sign in for a faster experience.

Supports **bold**, *italic*, and `code`.