Skip to main content

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.....

Labels:

Comments

Post a Comment

Popular posts from this blog

Food first post

My blogs' name is High-Tech Rojak but I don't recall ever talking about food. So here's a first. Just recently I got some free time and finally got to cook the pasta I've bought for ages. So here's an account of how it went down.. :) Okay. That's the thing I cooked. I have no idea what it's called. At first I was thinking of buying the ribbon ones, then my wife looked at the colorful spiral ones and said "why not get these? they're more colorful" and so we got them (yes, we know nothing about pasta.. :) So I boiled it, actually put some salt and oil into the water so that they won't stick, drained it and tadaaaaa, you'd get the above. I remember once I tried to cook macaroni and I didn't drain it after boiling it, it filled up the whole pot. LOL... Learned my lesson. Next up the sauce. Like I said we don't know anything about pasta so here's the ingredients we prepared. Yes ladies and gentleman. Instant pasta sauce all bottl
6 comments
Read more

Documentation is a must... after this.

I've been thinking quite a bit about documentation and the 'cost' it involves. And when I say documentation, I mean documentation in general about anything. One obvious case with the industry I'm involved in is user documentation (a.k.a The Manual). Creating great features in software takes time and effort but if it is not documented then the user won't even know about it and finally it never gets used. But then while documenting it you just wish that you're working on the next cool thing rather than have to write this up. So finally you end up not doing the documentation or doing it rather badly. Same thing with this blog writing. I have been doing some pretty interesting things with my phone (rooting it and using cynogenmod and all), some pretty significant life changes (my grandmother passed away) and a lot of other things which I should probably like to remember better or reflect more on it but not documented (here or anywhere permanent) and it would probabl
1 comment
Read more

The Future Of Gaming

I love playing computer games. It's what originally drove me to learn computer programming, I wanted to create my own games. Until now I still have very little success with that, but... I have learnt to program web applications quite well and earning my pay using those skills. And I love open source software. Ever since I started programming professionally, my main work OS has always been Linux (various distributions and all and currently on Arch Linux). I always install dual-boot because... hardware problems (some projectors and printers just couldn't be detected by Linux when I started out, that's mostly not a problem now) and mainly to play games (sure there was some open source games available, but apart from "Battle for Wesnoth" and "FreeCiv" I don't actually recall any games I've played extensively enough to be remembered). But recently the gaming scene in LinuxLand has improved tremendously, partly thanks to the Windows 8 app store like
Post a Comment
Read more