30 May 2024 / Technical leadership / 8 chapters

Check how the decision process fails

From How technical decisions break down as a team grows

Here's where I'd expect this kind of process to go wrong.

Document everything and you get a stream of trivial records that makes the important ones harder to find. Save durable records for choices with real alternatives, effects on other teams, difficult reversal or recurring confusion.

Records written after the work to tick a process box tend to justify whatever got built instead of capturing the actual constraints. Write the proposal before anyone's committed, then update it with the accepted decision.

A central approval board for every change turns into a queue. Reviewers lose touch with the domain, and teams learn to describe their work as local so it gets through. Keep central review for named shared contracts and high-stakes choices.

Old decisions that are still searchable but have no status will catch people out, because a careful developer can follow obsolete guidance to the letter. Superseded records need a visible marker and a link to the current answer.

Unwritten exceptions spread badly. A senior reviewer might let one team diverge for a good reason but keep the reasoning in a conversation, and another team copies the difference without the constraint behind it. Record exceptions next to the shared rule, with their scope and when they should be reviewed.

Sometimes the code becomes the only record of what the product means. It shows how things are built now, but not which behaviour is intentional, which constraint came from another system or which alternative is still off the table. Tests help if their names and fixtures carry enough context to explain the rule.

Ownership can drift towards whoever has the reputation. People become informal gatekeepers because they know the history, which makes it harder for newer people to grow into the work. Put the current answer, source links and review route somewhere the team can reach without needing the right person to be online.

Some assumptions never get looked at again. A choice made for one deployment model or customer group can stick around long after that condition is gone. Flag the assumptions likely to change and review them when something relevant happens, instead of scheduling a meeting for every record.

All articles