November 27, 2007, 12:05 pm
The Slow Death of the Technical Specification
By Lisa Agustin
The days of the web developer’s technical spec are long gone, writes columnist Richard Banfield: “In a world of intensely visual design, we have to ask why we still need to write massive documents to describe web products that real people will use.” According to Banfield, there was a time when it made sense to document everything before starting any software development, and that this way of doing things was largely a result of limited technology and lower design costs. These days, developing a web site or application demands a more agile approach–one in which visual tools play a key role:
“Once the priority of a project is established, the team should immediately move toward visualizing that idea. This can take many forms, but we have found that whiteboards and large pieces of paper work wonders to get everyone on the same page. Nothing slows down the creative process like a 60-page document, complete with spreadsheets and appendices.”
This has been our experience as well. While some engagements do require some type of written narrative — especially in cases where there needs to be a more detailed explanation of the application for a broader group outside of the development team — we’ve seen immense value in translating requirements into a visual form during all phases of a project. I would take Banfield’s comments a step further by suggesting that visuals are not just helpful tools, but can often replace specification documents as deliverables. Diagrams (for expressing high-level user experience), process flows (for explaining complex transactions), and heavily annotated wireframes (for describing functionality at the page-level) are “closer to reality” than a Word document that describes them. This makes the idea behind an application easier to understand and discuss, leading a group to consensus about direction much more quickly.
This is a valid position to hold but it risks understating a crucial element in many services — the transaction processing layer. IA, as a discipline, has too often treated the portion you describe as ‘process flows (for explaining complex transactions)’ with too light a touch for the inherent complexity involved. Whilst I dont desire to read any more 100 page ‘specs’, I do need to know specifically, and in advance, how transaction processing will be managed.
Posted by Simon Dessain on November 28, 2007 at 6:05 am
The “The Slow Death of the Technical Specification” is another reason why so much slipshod work is passed off as finished work. Preparing the technical specification is an initial and thorough implementation of the work on paper. The coded implementation is the second implementation based on the strengths and weaknesses of the first pager implementation. As Fred Brooks says, plan to throw one away; you will, anyhow.
A work needs to be reviewed. The customer needs to know that they are getting what they asked for. How do you review a working implementation — a web site, a desktop application, or an infrastructure? How do you review a paper implementation? People have been developing the skills and using the tools necessary to review a linear presentation of a work since secondary school. A very rare few people have the skills or tools to review a working implementation. Not having the written specification is short changing both the customer and the supplier. The customer gets something they are not in the position to review and the supplier is in the position of not knowing if the implementation what the customer wanted.
The weakness of the paper implementation that it does not define the coded implementation. The construction industries have “as built” blueprints. This are the original blueprints with annotations detailing the differences from the design and the construction (i.e. implementation). Software needs these too. We just don’t have them yet.
Unfortunately, I have supplied much software without initial or even afterward technical specifications. Hardly great moments in a software development career.
Posted by andrewgilmartin on December 1, 2007 at 3:19 pm