Design Notes are not Functional Specs

At my company, we don’t write Functional Specs, we write Design Notes. This post explains the differences and the thinking behind those differences.

Design Notes contain some Balsamiqs, some text, and the occasional table definition. Many people, when they see a Design Notes document think of it as a Functional Spec. They exist purely for the time before the software is written as an aid for developers and testers. Once there is software, the software is the spec. This contrasts with Functional Specs where any differences in the software and the spec should be automatically considered a bug, although it practice there are often things that got added without the spec being updated because it was too much work to update the spec.

Things change, and we want to spend our time building software, not continually updating documents about the software we’d like to build. When specs have to be kept up to date, it becomes incredibly difficult to finish the spec and actually start development. Every new idea from users, every question from developers, every clarification that testers ask for, they all require a new version of the document and every new version has to be sent out for review which triggers lots more feedback. While this is going on, it{781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f}u2019s tempting to halt development to avoid “unnecessary rework” and to allow the analysis to “complete”. Let’s get one thing straight: analysis is never complete and software will always evolve. Any process that assumes otherwise is a broken process.

The overhead of having to keep the spec 100{781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f} accurate can be so tortuous that getting to a final version of the spec often involves pressuring some stakeholders into accepting things they don’t like just so everyone can agree and move on. Having done that, it becomes politically very difficult to re-open the spec later on. So even the most obvious and important changes have to wait until “Version 2” because we can{781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f}u2019t possibly change the spec once it{781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f}u2019s been signed off.

Design Notes do present a challenge for testers. Traditionally a tester’s job was to ensure the software met the spec. Design Notes require the tester to be more involved in the design process and to think about whether something is really a bug before raising it. Often this will involve talking things through with analysts, developers and customers. We recognize that this is not easy, but we think this is treating testers as more equal partners in the development process. On the plus side, testers are not constrained by a spec; if something looks wrong, doesn’t flow well or is inconsistent, even if it’s doing what the Design Notes say it should, they are still free to raise it. Saying {781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f}u201Cit meets the spec{781c323b309d6e174625241ec7481c1d30d3b1f9955792182ab0278b30a7fb7f}u201D is not the end of the conversation.