Tuesday, 17 August 2010

Why are specs important?

When I used to work at my previous company, I always felt that specs were annoying and inconvenient and didn't really serve much purpose other than for ticking boxes for quality auditors or whatever. Then I came to my new company who have almost zero procedures or specifications and I now miss them. For those of you out there who are not convinced or those faux experts who claim "at the end of the day you have to start coding and see what happens", here are reasons why paperwork is important:

  • It is much quicker to define and review a concept or system on paper than it is to write the code. It is almost impossible to review a completed system in code because of the volume of information and any changes are generally impossible (at least to achieve in a robust way)

  • A document is easier to team review including with non-technical people/managers who can understand basic system info but not the detail

  • It gives visibility of intent to the customer, especially if there is more than one customer (this includes product managers and stakeholders). It is easier to argue and agree functionality when it is a single paragraph of text than to rip up a load of work later on in code and attempt to rewrite it without breaking things.

  • It allows changes to be measured against what was originally agreed which means its easier to say, "no we're not changing it because it was agreed" and equally easier for a customer to say, "this is not working compared to what was agreed, please fix it".

  • Changes to the functionality can be formally agreed and recorded electronically so no-one is in a position to easily argue that the system is "wrong" which usually means they personally think it should be different.

  • Often people will disagree about the intent or content of certain functionality perhaps as a balance between management requirements and the additional workload required but since these issues are agreed up front, either the manager can accept a reduction in functionality to appease the worker or they will insist that the worker does what the system requires of them even if they don't personally agree.

  • Various interworkings and calculations are much easier to write and review on paper before the sometimes significant amount of work required to actually implement those calculations.

  • By having processes that govern the production of specifications, if something bites you in the released product or perhaps in test, a note can go into the process that might say something like, "ensure you have considered any additional security that might be required" or "Consider the fact that you will interact with new data and it will probably require validation to be defined"