Yes Virginia, You Do Have A Spec

When you don’t have a specification, everything’s a bug. But in fact you always have a spec. Sometimes it’s an honest-to-goodness document recording what your feature team decides the feature should be. Other times your spec is somewhat camouflaged.

At the very least you have your application’s code. The moment your developers start writing code, that code becomes the only useful definition of how your application works. Sure, you may still have a document that asserts what *should* happen, but that code is what specifies what *actually* happens. You must know what your application really does before you can determine whether it is working correctly or not.

Code tells you what does happen, but specs are more about what should happen. Hopefully you have a large set of specs laying around posing as test cases. Each unit test, integration test, and manual test case anybody has ever executed against your application is effectively a spec for how your application should handle a specific case.

Every bug report you receive is somebody’s idea of what should happen presented as a case where it did not. Turning bug reports into specifications can be a lot of work, but this data is a gold mine of information.

Each of your customers has expectations of how your application should work. These specs cannot just be read but rather must be carefully extracted by talking with your customers, learning how they use your application, and asking them what they think your application does and how they think it works. Don’t be surprised if you discover that they see it quite differently than you do!

Listen to what your developers, testers, management, and marketing say about what your application is and does. Ditto press and analyst coverage. Again, this may be quite different than how you see things. Such conflicts of expectations highlight areas whose specs need clarification.

Work with your feature teams to determine what you want your application to be. In some ways this is the most important spec of all. After all, it’s y’all that will spend the next many months building the thing. If you don’t believe in what you’re building you’ll have a hard go of it!

Specs don’t need to be written down to be effective. If you’re working in a very agile manner, with all members of the feature team (yes, even marketing) in the same room, your collective memory may be sufficient to keep the spec alive. But the spec does need to be explicit, it does need to be understood identically by each of you, and everyone does need to believe in it. Otherwise you’ll just be a bunch of people in a room talking at each other who may manage to produce some software that some people may decide to buy.

To write outstanding software that people love you need a spec.

*** Want a fun job on a great team? I need a tester! Interested? Let’s talk: Michael dot J dot Hunter at microsoft dot com. Great coding skills required.

Comments (5)

  1. Han says:

    Yes, This a good thing to consider and practise.

  2. ---anonymous--- says:

    sounds like context-driven testing.

    IMO this blog entry would benefit from some links to the articles regarding the context-driven testing.

    btw, could you describe what "Great coding skills" includes in your understanding?

  3. On my team, "great coding skills" means "probably you could get a dev job".

  4. Anutthara says:

    Yet another nice post! BTW, why do you refer to Virginia in the title? Is this someone that asked you a q about whether a spec is needed in the prod cycle?

  5. This blog title is a take-off on the Americanism "Yes, Virgina, there is a Santa Claus", which you can read more about at

Skip to main content