A long time ago, a client that made software for restaurants handed me a BASIC application on floppy disks. With it came the source code and a printed user manual. “Just build us a new one,” they said.
That should have been simple. It was not.
The first thing we discovered was that the source code did not match the compiled version on the disks. So we could not even trust what we were reading. The second thing we discovered was the manual. It explained the easy parts with the kind of detail that made me wonder who it was written for: “To create a new product, click New. To save it, click Save.” Then, when it came to the actual business process, it said something else entirely: “Work in Progress. Check with Joe.”
Joe was the person who knew how restaurants actually ran. Joe was no longer with the company. We also had only about 100 hours of questions budgeted, and then we were on our own.
What happens when the business is not in the room
With a hundred hours, you can ask a lot of questions. You cannot learn the restaurant business in that time. So the team did what teams do when they are starved of context. We filled in the gaps with guesses. We looked at the screens, read the code, and inferred the business rules from whatever evidence we had.
Code is a record of decisions, not an explanation of why those decisions were made. A field named IsActive might mean the menu item is currently available, or it might mean the record has not been soft-deleted, or it might mean something a previous developer needed one Tuesday and never documented. The only way to know is to ask the people who use the system.
We did not have enough access to those people. The manual pointed us to Joe. The company had restaurants to support. The people who understood the software were busy keeping their customers fed, and the people building the replacement were in a different building making up stories.
The project failed. It was not merely late; it did not produce a system the restaurants could use. We built something that ran, but it did not run the business.
Documentation is not understanding
That project taught me a lesson: you cannot outsource business understanding to documentation.
A user manual is a snapshot of what someone thought was worth writing down at a specific moment. Source code is a snapshot of what someone thought was worth automating. Both are useful. Neither is a substitute for a conversation with the person who does the work.
This is why, when I start with a new client now, I ask to see the spreadsheets the users build themselves, not the reports the system generates. Those tell me what the system is missing. They show the questions people are trying to answer and the decisions they are trying to make. I wrote about this in Show me your Spreadsheets! back in 2020, and I still do it today.
The spreadsheets are a conversation starter. They replace “Work in Progress. Check with Joe” with “Tell me about the decision you make when this number turns red.”
The questions I ask now
These days I bring a different set of questions into those conversations. I want to know who is affected by a feature, why it matters, whether it touches revenue or loss, and when in the workflow it actually happens. I wrote about that framework in The Questions I Ask Stakeholders to Surface Edge Cases. It is the discipline I wish we had brought to the floppy disk project.
Those questions are about the gap between what the system records and what the human needs to decide. If we had asked them early enough, we would have spent less time guessing at screen behavior and more time understanding the business event that screen was supposed to support.
Requirements documents do not contain edge cases. The real work does: the table that wants to split a check six ways, the refund for a dish that never came out, the modifier that means “no onions” on one ticket and “extra onions” on the next, the report that only matters on Mother’s Day. You find them by talking to people while they do their job.
The floppy disk keeps showing up
The floppy disk story feels old, but the pattern is new again. In The Floppy Disk Test for Vibe Coding I wrote about a job candidate who showed up with disks full of wizard-generated FoxPro code. The UI looked real. The code compiled. Nothing there revealed the mind of a developer.
That is the same danger I see now with AI-generated applications. The tool can produce screens, endpoints, and schemas that look complete. They may even match the prompt. But if no one has asked the human questions behind the business, the result is the same: an application that runs but still fails the people it is supposed to serve.
The disks have changed. The test has not.
What I took from it
The failure of that project was relational, not technical. The development team was too far from the people who knew the business. The source code was treated as the source of truth, and the compiled application was treated as the target to copy. Both were incomplete.
If I were starting that project today, I would insist on embedding the team in the restaurants before writing the first line of code. I would record conversations, transcribe them, and use them as the real specification. I would distrust the manual and the existing source code, because both are symptoms of a system that has already lost too much context.
The artifact is a record. The conversation is the understanding.
Leave a Reply