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

Comments

Popular posts from this blog

haproxy on Centos 7 with SELinux

Setting up haproxy and varnish with reference to the configuration from these sites: http://sharadchhetri.com/2014/12/20/how-to-install-varnish-4-version-on-centos-7-rhel-7/ https://www.upcloud.com/support/haproxy-load-balancer-centos/ And finally can access plone on the server. But when I check the haproxy status, only client1 can be accessed. All other clients were down with general socket error, permission denied. Googling a bit I finally found out it was due to SELinux. Refer to this page: http://stackoverflow.com/questions/26420729/haproxy-health-check-permission-denied With the solution from that page, I installed policycoreutils-python and tried to run the command given: semanage port --add --type http_port_t --proto tcp 8081 But that command failed with the error that the port was already defined. When I looked it up using: semanage port -l | grep 8081 It belonged to some other type (transproxy_port_t). When I tried to delete the type using: semanage port -d -t transpro…

Installing Centos 7 on HP G7 Server

When I first initially tried it, the installer cannot detect any local hard disk to install to. After much googling found out that it was because a certain driver for the Smart Array Controller is no longer available on Centos 7. To allow for use of the new driver on old hardware, you need to enable the option. Once the DVD has booted and on the first menu screen, highlight the first option and then press tab which would bring you to a command line where you can add additional parameters to boot. Add the following parameters: hpsa.hpsa_allow_any=1 hpsa.hpsa_simple_mode=1 And then press enter to boot. You should now be able to install as you wish. After installation, on the first boot, make sure at the menu, press 'e' to edit the parameters and add them again. Then once booted, go to /boot/grub2/grub.cfg to permanently add the parameters to the menu. Refer to http://serverfault.com/questions/611182/centos-7-x64-and-hp-proliant-dl360-g5-scsi-controller-compatibility and it&#…

Me and my sleep apnea

I have been suffering from sleep apnea for quite a few years already. It started to show when I was still with OSCC some 6 years back when I would sometimes "accidentally" sleep at my cubicle. Early on I just dismissed it as because I was growing fat (we ate a lot at OSCC.. :P and I barely went anywhere except my cubicle) and also because of babies. Oh babies.. those cute little things that keeps you awake at night so that they can be so cute and charming when your friends and relatives come over the next day. So it was dismissed. Later on I got more and more used to sleeping at work, started associating it with my lack of motivation and sometimes feeling of downright depression. And I kept growing fatter and fatter, which I assumed was the reason why I was getting more and more tired.

But then around 2 years ago a friend of mine suggested maybe I've got sleep apnea. And a few other people suggested I go to a sleep clinic and all that. Put it off for quite a while. Until…