Painless Functional Specs

Documentation.... Documentation never change.... (end fallout war never change reference)

I don't particularly like documentation. Sorry, let me rephrase that. I LOVE good documentations, I just don't like doing them. That being said, I need to start to really learn how to do it properly and meaningfully so that I too can generate great documentation which everyone loves to refer to but doesn't like to do. So where do I start? From the legend himself, Joel Spolsky. You can read them from his old blog but I'm just going to do a summary here for my own reference.

His first essay is on why functional specs should be done. Well, it's so that Bob the programmer know what to code out, it's so that Tina the marketing exec knows what features are available and what to say to the customers, it's so that Dol the manager knows what on earth he is managing.

Next, he outlines what should be in a spec. In short there should be

1. A disclaimer
• A paragraph saying "This spec is not complete" will avoid people coming to bite your head off
2. An author. One author.
• Specs should be owned by someone. A real person. Not a group or a committee but an actual breathing, living person who will take responsibility for the spec. A large program can have many small specs written by one person each.
3. Scenarios
• Think of some real live scenarios for how people is going to use it
4. Nongoals
• Cull features straight away to avoid infinite time and cost
5. An overview
• Everybody who reads this will get the big picture, then the details will make more sense
6. Details, details, details
• Mind numbing detail
7. Open issues
• It's ok for the first version of the spec to have open issues
8. Side notes
• Useful factoids which might be useful to just one of the group of audience for the spec
9. Specs need to stay alive
• The specs always reflect our best collective understanding of how the software would work

In the third installment of the writing, he mentions about the importance of the Program Manager. 

And in the fourth and last installment he gives some tips for spec writing. They are:

1. Be funny
2. Writing a spec is like writing code for a brain to execute
3. Write as simply as possible
4. Review and reread several times
5. Templates considered harmful

And that is all more the less what I need to know. So here I go writing out specs like a boss.....