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

Unknown said…
The King Casino | Ventureberg
Discover the rise and fall www.jtmhub.com of the king casino, one https://deccasino.com/review/merit-casino/ of the world's largest ventureberg.com/ The Casino is operated by 1xbet korean the King 바카라 사이트 Casino Group. You can

Popular posts from this blog

Dell Inspiron Mini 9

Yesterday went to Low Yat to buy my cousin a sub RM 1500 notebook. Of course with that kind of price tag it would have to be a netbook jelah. Anyhow, I was short on time so I didn't get to browse thoroughly. Just went for one quick round around level 2 and picked the one that I thought would fulfil his need. The thing is, as soon as I stepped out of the lift there was a shop that sold the new Dell Inspiron Mini 9 for only RM 1199. I was suprised. Just 1199. I couldn't believe my eyes. With original Windows XP and all. RM 1199. I thought there must be something wrong. Better survey first. So went around level 2. There was nothing that could match that price. Most of the other netbook from acer, asus and lenovo even was around RM 1600. So I decided I'll just go with the Dell lah. But to tell you the truth if I had money to buy for my own use, I'd go with the Lenovo Ideapad S10. Fuh.. she's one sweet mama... Smooth rounded curves, slim white profile. Pergh.. But anyway

First godot game published

I haven't published anything in google play for a very long time. I'm very happy to finally introduce my latest project to the public. It is a casual game called..... Add Block. Yeah.. The best original game name award coming right up. But seriously, try it out. Find in at the play store here . I love playing casual games on my phone. It's great to pass the time. But it doesn't really do anything for your skills. Or at least not anything for real life important skills (yes, I don't consider being able to identify the consecutive shapes or color as really important). So I decided to create one. So in this game, you practice your math skills. Find the adjacent blocks that add up to the total you need. So it's math, math is important right? Right?.... The levels are unlimited, the idea is that you keep on playing until you can't anymore. You'll die if you finally can't get the number of wins required to pass the level in time. You only have 100 se

Rendering template from string using thymeleaf in spring

Finally solved a very big problem for me... How do I render a page in spring framework that uses the thymeleaf templating engine? The string most probably will come from the database. After long hours of searching and trying, I've got it. First I've got a clue from this particular stackoverflow question . But following an example from there got me an error about class not found for ognl.PropertyAccessor. That solution was found here . So here's how I finally done it... First thing is to create a service where that service can be used wherever you need it in your spring app. @Service public class PortalService { private TemplateEngine templateEngine; private final static String TEMPLATE_LOCAL = "US"; private TemplateEngine getTemplateEngine(){ if(null == templateEngine){ templateEngine = new TemplateEngine(); StringTemplateResolver templateResolver = new StringTemplateResolver(); templat