Darryl.net

In the traditional waterfall approach of software development, people document unknowns. Specifications are written at the beginning of the process. The team attempts not only to lay out the features they want to build, but also to posit the most efficient manner of development. By doing so, the team draws on the past mistakes of its members. Next, the team guesses what mistakes they might encounter based on the features requested and attempts to prevent these mistakes. The PRD and TRD are complete.

Why not just rely on your team members to recognize these mistakes if they encounter them?

What do we gain if we skip the unwieldy specifications process and only document the mistakes we see along the way? First, if your team members do not recognize the mistake when they see it appearing, then they didn’t have enough experience to predict it in the first place. You save time by not thinking about what might never happen. Second, design errors are now clearly visible and can be discussed and addressed. Normally these mistakes go undocumented (except the bug report which is the symptom, not the cause). Finally, while your PRD may be useless to other teams in the company, a database of mistakes and solutions is pure gold.

Let’s consider one of the most basic ‘user needs’ as an example: “I need to go to the bathroom.”

When the first bathroom was designed, the Neanderthal architect did not say: “For version 3 of our bathroom, we will have large common rooms with privacy stalls. To prevent theft of the materials that compose these stalls, we should begin making screws now that cannot be unscrewed.”

Instead, it went something like this:
“I need to go to the bathroom, so I’ll dig a hole.”
Mistake: No privacy with hole outside. Build shack.
“Our workers should wash their hands, let’s attach a sink to the outhouse.”
Mistake: It’s freezing outside in the wintertime. Attach shack to shop.
“It smells in the shop now, let’s add a vent.”
Mistake: Flies come in vents. Use fan to make forced air vent.
“The fan sparked an unnoticed fire and burned the block down.”
Mistake: Bathrooms are seldom visited spaces. Install fire detectors and sprinklers.
“Bathrooms are boring. Let’s put up funny pictures.”
and so on…

These mistakes and solutions were recorded and now comprise a county’s “building standards.”

Now, imagine if you had this “database of mistakes” within your company:
Mistake: TCP does not work well for voice applications on our proprietary servers. Use UDP for voice applications.
Mistake: If you install company_widget_g and company_widget_f together, people can break in to the system. Have your application use one or the other, or make this modification to company_widget_f.

By doing a quick search for ‘company_widget_f’ when you are about to install it, you’ll avoid a few weekends at the office. By looking at another project’s PRD or TRD, you wouldn’t have discovered this bit of gold.