We’re working through an overhaul of our software development lifecycle at a company I’m consulting with right now.
In the couple years before I came on board, there were a few horror projects that were 100% over schedule, lack of communication, tons of problems right after launch, etc. etc. The then-CTO has left to spend more time with his family, and the new guy (my direct boss) is doing the smart thing and pushing Agile concepts pretty hard. However, we have a consulting agency in that is very familiar and comfortable with classic waterfall methods, so we find ourselves duking it out over SDLC philosophy as we work towards common ground.
Currently we’re talking about functional specs. To my mind, the functional spec outlines what we’re going to build, and how it should work. That’s where we all agree. The disagreement starts pretty soon after that. I believe specs should be human-readable. I believe specs should only be detailed where necessary, and that unnecessary or obvious detail just leads to confusion. I believe pictures tell a thousand words, and fake screenshots are super valuable. I believe specs should be brief.
Most contentious, perhaps: I believe specs should be written at multiple contextual levels, in order to most effectively relate the information. I believe specs should get the big picture right before drilling into endless details. I might refer to this as the sieve theory of specifications: if your discourse is limited to a single level and get too detailed, your spec ends up like a sieve, and you risk letting important points about the application fall through the gaps because of confusion and lack of perspective.
Tell a story about each feature in the software, and fill in detail only where you need to. Show a nice picture (learn to use Visio). Use readable language. Don’t clutter up your spec with endless lists of bullet points or 220.127.116.11.1.8 nightmarish levels of outlining. Don’t write your spec like you’re writing a legal brief, with SHALLs and WILLs and SHOULDs and MUSTs and MAYs and CANs all competing for thinking space.
While googling for “worst functional specification” and “terrible functional specification”, and coming up with zero results (very interesting!) I found the Getting Real 37 Signals website and like this quote very much:
Go with a briefer alternative that moves you toward something real. Write a one page story about what the app needs to do. Use plain language and make it quick. If it takes more than a page to explain it, then it’s too complex.