exo : blah

I both dread and enjoy writing specs for software. The dread bit is the having to write down in plain english concepts that are far easier to demonstrate in code; it's taking phrases such as "and then we stuff it into a database" that make sense to you and actually having to detail what this will mean. The fun side is that when you're, or at least I'm, fleshing out the initial draft quite a few useful ideas usually occur.

Whenever I have to write a spec I generally start out by just spewing everything that comes to mind onto paper or into my text editor of choice. Once I've done that I try and organise it into some sort of structure and translate it all into something meaningful. The first bit is fun and interesting, the second is dull but it's what turns it into something useful as it forces you to think about it how things tie together. Sometimes it lets you see things you've missed, sometimes things that shouldn't be there. It makes you look at the thing as a whole and forces you to think about why things should be done. Or at least it should.

The problem with the second bit is trying to produce something that's useful to anyone who has to implement it but meaningful to anyone non technical, and by non technical I mean non programmers. The latter generally have no interest in exactly how things are to be done but more in what is to be done, how long it will take and so forth. The former are more interested in why they have to do it that way.

That last comment might seem snide but it seems to me that the why you have to do something a certain way is the key. With regard to the code being the photo section one of the requirements is that it has to be written in Perl because it's the language I know and like best and this is supposed to be for fun. It is though, a rather arbitrary requirement. There is no reason why you couldn't do it in Python, PHP, Java or various other languages. Once you know that's why the requirement is there though it's clear that "but if we used language X" is not a valid point. A more meaningful example is that I want the site to be templatable. Now, in order to achieve this I could just whack some perl that prints out XHTML into a file and then just have the code pull that in and process it as perl at the relevant point. The problem with this is that the reason I want to use templates is to enable me to provide a well defined interface between the code and what I display. Evaled files do not do this although they does meet the requirements. Without understanding why templates are to be used you can't make a good decision on how to implement them.

Of course, you also have to pay attention to the what.

With the photo code the spec is aimed at me so it leans more to the well organised brain dump end of things than an easily digestible essay on my vision for a photo gallery application. I am, after all, doing this for fun.