Teardown: reading the spreadsheet as the specification

We inherit systems more often than we start them. This is how we read one: what we look at first, and what each thing tells us about decisions made by people we'll never meet.

The spreadsheet somebody maintains by hand is the most accurate specification in the building. It has no budget, no committee and no aspirations. It describes what the work actually requires, which is more than the requirements document manages.

WHY IT IS MORE HONEST

A requirements document describes what people believe should happen. A spreadsheet describes what they do to get through the week. When those disagree, the spreadsheet is right, because it's under daily pressure from reality and the document isn't.

It also survives selection. Every column in it exists because someone needed it badly enough to type it in repeatedly. Nothing in it is speculative, which is not something you can say about any feature list.

HOW TO READ ONE

Start with the columns nobody can explain the name of. Those are usually where two concepts got fused because the system forced a choice. Then look for the colour coding, which is almost always an undocumented state machine. Three shades of yellow means three states your model needs.

Then find the comments. Free-text notes are where the exceptions live, and the exceptions are the actual domain. Read forty of them in a row and you'll have a better model than any workshop produces.

The exception handlers were the most honest documentation in the repo. Every branch that swallowed an error marked a spot where schedulers had once been paged and somebody had made it stop.

REPLACE THE JOB, NOT THE FILE

The instinct is to build the spreadsheet as software, which produces a worse spreadsheet with a login page. The point isn't to reproduce the file, it's to remove the reason it exists, usually a state the real system can't represent or a handoff it can't see.

Fix that and the file stops being updated on its own. That's the outcome to aim for. Nobody needs to be told to abandon a workaround once the workaround stops being necessary.

The schema told the real story. Three nullable columns added in one migration, all named after a work order field, all populated for precisely the weeks when a technician drove three hours to a job someone had already closed was an open ticket.

WHERE IT GOES WRONG

• Reading the requirements document and not the forty free-text notes that describe the real exceptions.
• Banning the spreadsheet before the system can represent what it was tracking.
• Building the spreadsheet as software, and shipping a worse spreadsheet with authentication.
• Ignoring the colour coding, which was the state machine nobody wrote down.

Read the spreadsheet before the requirements. Then remove the reason it exists.

THE VERDICT

Better than its reputation. Most of what looked like bad engineering turned out to be a sensible answer to a constraint that had since been lifted, and nobody had gone back to check.