- Elisabeth_The_Third
- There is nothing more powerful as an idea whose time has come
- Los Angeles, United States
- Offline
Business Blog
Painless Functional Specifications - Part 2: What'...
November 19, 2008
Painless Functional Specifications - Part 2: What's a Spec?
Here are some of the things I put in every spec.
http://www.joelonsoftware.com/articles/fog0000000035.html
A disclaimer. Pure self defense. If you put a paragraph saying something like "This spec is not complete", people won't come into your office to bite your head off. As time goes on, when the spec starts to be complete, you can change it to say "this spec is complete, to the best of my knowledge, but if I forgot something, please tell me." Which reminds me, every spec needs:
An author. One author. Some companies think that the spec should be written by a team . If you've ever tried group writing, you know that there is no worse torture. Leave the group writing to the management consulting firms with armies of newly minted Harvard-educated graduates who need to do a ton of busywork so that they can justify their huge fees. Your specs should be owned and written by one person .
If you have a big product, split it up into areas and give each area to a different person to spec separately.
People should take responsibility and ownership of the things that they specify. If something's wrong with the spec, there should be a designated spec owner, with their name printed right there on the spec, who is responsible for fixing it.
Scenarios. When you're designing a product, you need to have some real live scenarios in mind for how people are going to use it.
The more vivid and realistic the scenario, the better a job you will do designing a product for your real or imagined users.
Nongoals. When you're building a product with a team, everybody tends to have their favorite, real or imagined pet features that they just can't live without. If you do them all, it will take infinite time and cost too much money. You have to start culling features right away, and the best way to do this is with a "nongoals" section of the spec. Things we are just not going to do . A nongoal might be a feature you won't have ("no telepathic user interface!")
An Overview. This is like the table of contents for your spec. It might be a simple flowchart, or it might be an extensive architectural discussion. Everybody will read this to get the big picture, then the details will make more sense.
Details, details, details. Finally you go into the details. Details are the most important thing in a functional spec.
Going into outrageous details, while talking about all the error cases for the login page. -- What if the email address isn't valid?What if the password is wrong?
All of these cases correspond to real code that's going to be written, but, more importantly, these cases correspond to decisions that somebody is going to have to make. Somebody has to decide what the policy is going to be for a forgotten password. If you don't decide, you can't write the code. The spec needs to document the decision.
Open Issues.
It's OK for the first version of the spec to leave open issues. When I write a first draft, I always have lots of open issues, but I flag them (using a special style so I can search for them) and, if appropriate, discuss the alternatives. By the time the programmers start work, all of these need to be solved out.
You might think it's OK to just let the programmers start on all the easy stuff, and you'll solve the open issues later. Bad idea. You will have enough problems resolving the new issues that come up when the programmers try to implement the code, without having old open issues around that you knew about in advance and could have solved then. Besides, the way you resolve anything non-trivial may have a major impact on how the code should be written.
Side notes.
While you're writing a spec, remember your various audiences: programmers, testers, marketing, tech writers, etc. As you write the spec you may think of useful factoids that will be helpful to just one of those groups.
Flag messages to the programmer, which usually describe some technical implementation detail, as "Technical Notes". Marketing people ignore those. Programmers devour them.
"Testing Notes," "Marketing Notes," and "Documentation Notes"
Specs Need To Stay Alive. Specs needs to be updated frequently. The updating continues as the product is developed and new decisions are made. The spec always reflects our best collective understanding of how the product is going to work. The spec is only frozen when the product is code complete (that is, when all functionality is complete, but there's still testing and debugging work.









