The Importance Of… Specs

Have you ever built a house? It’s an analogy often used when developing software. So, have you? Me neither, but one of the things that most people understand about building a house is you need architectural plans. Floor plans in particular will tell you the dimensions of each room, detail fixtures and electrical items, note finishes and construction methods, and so on. It doesn’t just tell you where a door is, but also which direction the door will open in. It means when the construction crew turns up, they don’t need to ask how many bathrooms you want, and where you want to put them. This is all perfectly logical. No one would be accused of stalling when no floor plans are available.

For some reason, this doesn’t translate to software development in quite the same way. Sometimes feature implementations will be requested without more than a description of an idea. Developers will receive it and have hundreds of questions, because an essential consulting and requirements gathering stage has been skipped, and there is no spec for them to implement.

Why does this happen? Mainly because like all analogies, it will break when stretched. Developing software is often not like building a house. Moving a wall is costly – it is easy to understand that because you can see the physical effort involved. In our analogy, moving a wall in software does not afford the spectator quite so clear a view – it can be difficult for someone without a development background to understand why the changes they’re asking for are complicated and expensive to undertake. After all, if repainting the walls is as simple as changing a hexadecimal reference, why should moving the kitchen to the back of the house be any more difficult?

Another problem that seems common is a basic misunderstanding about agile processes. Look up “agile” in a dictionary and you’ll see it described as flexible, nimble, acrobatic. This is what people understand when you say you’re agile, and not so much the idea of iterative development processes. “Well, they’re flexible” they’ll think, “we can always change it later”. And yes, you can tweak things as you go along, but putting the basement in the attic isn’t really a tweak.

Perhaps more importantly, there is a fundamental difference between commissioning your dream house and requesting a change on a software product. The former is often a deeply personal affair, in which the customer is willing to invest their time as well as their money. Getting a customer to invest their time in defining the exact behaviour they want their application to have appears to be much harder – after all they’ve outsourced the work for a reason. I’m told some companies will even reject customers who aren’t willing to invest their time in this way.

Some time ago, Steve Yegge wrote an absolutely brilliant blog post entitled Have you ever legalized marijuana? If you haven’t read it, please read it now. Go ahead, I’ll wait. Done? Good, isn’t it? Steve makes a very strong point in the article – that what seems like a simple idea, which at first glance makes perfect sense, may turn out to be completely insane when it comes to implementation. If customers write a spec they might see this – the process of writing the spec will force them to think about how it might all work, and they might quickly come to the conclusion that it’s not going to work. More often than not, however, the job of analytical thinking will fall to a development team. This tends to make sense, as this is something developers are well equipped to do, and which they are good at.

But what happens when developers have to think about how to move the basement into the attic, or their feedback isn’t given due consideration? Steve mentions something which isn’t necessarily front and centre of the article, but which I’ve found to be true:

Because that kind of shit happened at Amazon pretty much every week I was there, for almost seven years. (And astonishingly, we actually managed to launch at least half those crazy ideas, by burning through people like little tea lights.

You will burn out your developers. Working on insane projects will lead you to insanity. So not only will you have to deal with the logistical nightmare of working without a plan, suffer the delays and extra expenses that that will incur, and strain the relationships with your clients, you will also find yourself having to recruit more often (and consequently spending more time and money on training).

If you take away only one thing, make it this: if you set off without a spec, you will never know whether you’ve delivering what was expected. I know, I know – sometimes it feels like the way to go about a feature is to start coding and see what’s possible (I’ve done this myself). But even in a healthy agile environment, a spec will provide you with a solid platform to start off from. Spend the time to prepare a spec and discuss the issues around it upfront, and save yourself the strife.

Photo by Will Scullin via flickr.


9 thoughts on “The Importance Of… Specs

  1. Let’s not also forget that with that staff burnout comes staff turnover and, inevitably, a loss of knowledge making products harder to maintain long-term!

    Get your house built by one builder and then ask a different builder to come in after and move a wall, do you think the quote will be higher or lower?

    1. Yes, the loss of knowledge that comes from high staff turnover can be very problematic. I was actually planning to write about it in an upcoming post. 😀

      I think the analogies tend to break down if you push them out too far, but I can probably stretch to say that the new builder will not know whether any pipes or electrics run through the wall, and the quote might therefore be lower, but the cost higher… unless the builder has access to some up to date electrical and plumbing plans. Quoting is easier with experience, and you should document your code. 😉

  2. Really liked the article, also the link about “shit’s easy” attitude is something I haven’t seen before. have so many people to send it to )))

    strangely enough, I have experienced a situation where spec’s were so thorough that all the developer had to do is put the line of code from spec into the file from repository. sort of defeated the purpose of being a developer in a way. also overloaded the analysis team. but that’s probably better then when you don’t have enough spec

    1. Glad you liked it Arturs! Sounds like a company with a heavy emphasis on the analysis part of development. I presume with larger developments there would have been less copy/pasting?

      1. Yepp, the larger projects had less of copy/paste but those ones came rarely mainly due to the product being out the for a long time and not requiring many new features. analysis part was big there which in a way made dev’s feel rudimental and made a lot of people leave or switch to analyst position. the way the things were going there made me think that the aim is to make the most thorough analysis using workforce in UK and outsource the implemintation and QA to other countries with cheaper workforce. which in my opinion is a debatable strategy

        1. Interesting. I suspect if the strategy was to define the architecture in-house and outsource the implementation, they might suffer in the long run, as developers working only on the theoretical solution might lose sight of more practical aspects (and you really need the practice/experience to be able to define solutions).

Leave a Reply

Your email address will not be published. Required fields are marked *