When to abandon specifications

PM Clinic: Week 27 discussion summary

Compiled: 5/9/2005

The Situation:

The current debate raging across my development team is about how long into development specifications should be maintained. Who should get to decide when specs get updated, if at all? Has anyone in the real world ever continually updated them every day and kept them in sync until release? Was it worth it? How close to daily updates should we be trying to get? How late in the cycle do they need to be kept in good shape for? Who should decide when specs are to be abandoned? The dev team? the test team? The marketing team? the PM team?

Quick answers: Never, sometime, Always

Just to set the framework there are four possible answers to this question.

1. You update specs forever (Never abandon)
2. You abandon them midway through development (sometime)
3. You abandon them at some point after release. (sometime)
4. You never write specs to begin with (Infinite abandon).

Often #2 happens, but with the intent that the team can come back at any time and update the specification. In this all too common situation the the spec is never formally abandoned, but left in an ambiguous state where no one, other than perhaps the spec writer, is sure what's going on.

What problem do specs solve

Before you can figure out how often to update specs, it's worth thinking about what problem they solve for the team.

• Human memory sucks. Writing things down is more reliable than your brain.
• Provides a reference for later on as to why a certain decision was made.
• Good specs support the team in making things.
• Good specs explain the complexities people need to understand or are likely to be confused by.
• The quality of test plans, development estimates , and documentation are based on the quality of specifications.
• Specs are often the only documentation for what happened and why for people that come later.
• Updating specs only matter if people are still reading them.
• Specs tend to be read if they are the fastest or best available resource for answering questions.
• Specs don't solve problems - it's the questions they answer for people that matter.

So in some cases there might be simpler, faster, smarter ways to achieve these effects than don't involve updating specifications. In other cases updating the specification is probably the best way to communicate to the team what's changed,

But always remember: you ship code, not specs. Never confuse the making of specifications with the making of code and products.

Different kinds of specifications

One element of this debate was what specs consist of. Are they high level descriptions of functionality (requirements), detailed engineering plans (technical specs), or detailed designs of User interfaces and the end-user experience (feature specifications). The value proposition for the spec changes depending on what kind of specification you're talking about.

Another consideration are the programmers. What do they need from specifications? Or more specifically, what information will they depend on specifications to obtain?

Before you make the argument for or against updating, be clear on what kind of specification you're talking about, who will use it, and what they'll use it for. Make sure that the customers of the specification are heavily involved in helping you to figure out where to invest your specification time.

Time writing specs vs. time suffering without specs

There was much debate on the list about the tradeoff of time spent writing specs, vs. time lost by those seeking answers to questions that should/could have been answered by the spec. Also, time is lost by people making mistakes that a decent specification could have avoided. If you consider DCRs (design change requests), integration issues or certain kinds of bugs as things possibly avoided by better specs, the costs of lousy or out of date specs are tangible.

If you don't write specs at all, or don't update them you're making a bet:

Time to write/update > time team will spend suffering

If you do write specs and invest in updating, you're making the opposite bet:

Time to write/update < time team will spend suffering

Several people in the discussion were strong spec advocates: they invest time in writing and updating specs and felt their teams appreciated (and in some cases depended on) this effort.

Before and after making these kinds of bets it's important to involve the team. Before writing specs you should listen to what the team needs, and after writing specs you should listen to their opinions on how effective the specs were in satisfying them. You can't evaluate the bet without involving other people.

Contributors

David Gorbet, Denise Neapolitan, J Kremer, Karen Barrett, Neil Enns, Jacquelyn Krones, Steven Levy, Mark Colburn, David Tate, Timothy Misner, Scott Berkun (editor)

About PM-Clinic

The pm-clinic is a friendly, wise, open forum for discussing how to lead and manage teams of people. Each week a new situation is sent to the list and we share advice, ideas and stories. Anyone can join as long as they follow the simple rules.