Recommended Reading: Painless Functional Specifications

Published: 18 September 2016

Way back in 2000, Joel Spolsky wrote a series of articles on his 'Joel on Software' blog (highly recommended) that discussed Functional Specifications. Now, given that this was written back in 2000 a lot of people will say it is out of date and no longer applicable. But I think there are many valid points in his set of articles that any BA should think about.

Below I have provided a link to each of the four different articles in the series, along with a sample quote from each. You may find that what Spolsky has to say resonates for you, whether you follow an 'Agile' or 'Non-Agile' process.

Part 1 - Why Bother?

"I believe that on any non-trivial project (more than about 1 week of coding or more than 1 programmer), if you don't have a spec, you will always spend more time and create lower quality code."

Part 2 - What's a Spec?

Some programming teams adopt a '"waterfall' mentality: we will design the program all at once, write a spec, print it, and throw it over the wall at the programmers and go home. All I have to say is: Ha ha ha ha ha ha ha ha!
This approach is why specs have such a bad reputation. A lot of people have said to me, specs are useless, because nobody follows them, they're always out of date, and they never reflect the product.
Excuse me. Maybe your specs are out of date and don't reflect the product. My specs are 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.)

Part 3 - But...How?

Since then, program managers at Microsoft gather requirements, figure out what the code is supposed to do, and write the specs. There are usually about 5 programmers for every program manager; these programmers are responsible for implementing in code what the program manager has implemented in the form of a spec. A program manager also needs to coordinate marketing, documentation, testing, localization, and all the other annoying details that programmers shouldn't spend time on. Finally, program managers at Microsoft are supposed to have the 'big picture' of the company in mind, while programmers are free to concentrate on getting their bits of code exactly right.

Part 4 - Tips

The biggest complaint you'll hear from teams that do write specs is that nobody reads them. When nobody reads specs, the people who write them tend to get a little bit cynical.