Edit: There’s now a counterpart to this entitled “Sysadmins: how to make the programmers love you“.
As a coder working for an organisation you are focused on building something to meet a defined spec. This spec will say things like “background should be blue”, “tabulated interface for user management” and “should not crash”. It may come with a set of images stitched together by a UI designer of how the site/app/thing is expected to look – either crayoned on the back of a fag packet or more likely mocked up in Photoshop so the UI programmers can pull it apart again for the logos and buttons. In a really good spec you’ll find a storyboard defining how it should behave, ready-made content and all the copy up front. We wish.
Things are not always like this. Sometimes in projects where the end result is not entirely defined (“doomed ones”) the spec may be little more than a set of wireframes and a brief hand-wavy description about what it is to do. Hmm.
But so far so good. It is positive that a spec exists at all and that we have some consensus on what we are making. From an engineer’s perspective the better defined and more rigid a spec is the better – the more agreement we can have about the location of a target, the higher our chance of hitting it.
The most common problem with specs is when they’re written by someone without an idea of the things programmers really need to know. They know what they’d like the product to do but overlook “make it robust” or “make it easy to setup on our CentOS 5.5 servers”. To non-engineers these objectives are obscure and here a problem arises – when they go unmentioned it’s easy to fulfill the specification while producing an article that’s a total pain in the butt. A project may be declared a success but still it can be excruciating for people to maintain, compile, release, troubleshoot or in any other way interact with.
Here’s how to avoid it…
Continue reading →