For anyone who’s worked in the website, software or application development industry for more than five minutes, I don’t need to explain the need for a really good specification.  It ensures that all parties – both developers and clients – are fully aware of what will be delivered, and it gives you something to refer back to when additional functionality is requested, to prevent scope creep within the project.

We’ve all seen projects where the slow but inevitable process of adding features to satisfy each new idea or new stakeholder causes the whole thing to flounder in a mass of mismatched expectations – developers work harder only to result in lower client satisfaction. No-one wins.

Essentially, good planning, and the ability to write a solid, specific and clear specification is often the key difference between a successful development project and an unsuccessful one. But good specifications are tough to write, so how do you get one that works?

1. Keep costs fluid until the spec is complete.
   All costs are estimates until the specification is finalised. They have to be. The very process of writing the spec finalises the development requirements, and until those requirements are finalised, the cost cannot be fixed.  A builder won’t issue a quote until he’s seen the architect’s drawings, you can’t issue a final quote until you have your spec.
2. Understand what kind of specification you’re trying to write.
   Typically in development projects there are two types of specification – functional and technical.  And there are two different types for a reason – they fulfil two separate roles, so understanding which one you’re producing and keeping them separate is critical. A functional spec tells you what, but not how. It lists user features, sometimes known as stories, to outline what the user will be able to do on or with the website or application (“user will be able to view outstanding orders”). A functional spec, or a partial one, is sometimes produced by clients as part of the briefing process.  A technical spec, on the other hand, outlines how the features will be delivered, and should cover everything from the coding language, platform and system architecture to sitemap, wireframes and URL.
3. Information gathering first
   A lot of larger development projects will involve a huge amount of information gathering before a specification can be finalised – be it reviews of existing solutions,  briefings, brainstorming with stakeholders, research and focus groups, or usability studies.  Some will just require a list of required user features to be written up into a functional spec and then translated into a technical spec. In either case, ensure you’ve gathered all the input before you start trying to create the spec – otherwise it’s a movable feast from the word go.
4. Be consistent in outlining basic requirements
   Writing specs is time-consuming because they are typically so bespoke, but you can make things easier by ensuring you’ve got the basics in a template. This not only gives you a starting point but ensures that the basics don’t get missed. Examples of this are the combinations of platform and browser support undertaken, hosting requirements or expectations, accessibility compliance  etc.
5. Be specific & measurable – don’t ignore uncertainty!
   Specification. The clue is in the name. If it’s not specific, it’s not doing its job. Be specific when documenting everything. If a deliverable cannot be quantified into a set of numbers, or a defined goal, then refine it until it can be – and this may mean breaking down large chunks of development into smaller bite size chunks until they can be realistically documented. There absolutely will be the temptation to gloss over things, thinking “we’ll sort that out later” or “there’s a couple of ways we can handle that, let’s see how it goes”. But those are traps for the unwary which will almost certainly catch you out at a later date. If something can’t be made specific, go back to your client and ask questions as to how they’re expecting it to work, or back to your developers and ask how they’d recommend delivering it, or both, and discuss until you have a specific answer.
6. Work through the user journey using flowcharts and wireframes
   For most website development projects, a specification is not complete until you’ve documented the various key user journeys with a flowchart (or series of flowcharts), starting with the homepage and running through all the key processes identifying the key pages or stages of user interaction. Once the key pages/stages and their relationship to each other have been defined, you can also produce very basic wireframes for each key page/stage, blocking out not how the page will be laid out, necessarily (that’s a design decision), but certainly what’s on the page and how it relates to other pages.
7. Consider risks & mitigations, assumptions & dependencies
   These may not go into the specification document but should be written into your development plan alongside your spec.  As you look at each stage of what needs to be delivered, consider and document the risks, how you can mitigate the risks, the assumptions upon which your spec rests, and any dependencies. So, your client has said that they will be setting up a brand new hosting environment for the project to an agreed specification by the end of this month. Your project specification assumes and depends on that server environment being available on time and being as per the agreed spec. The risks are that it is delivered late, or that the hosting environment is not as expected. You might mitigate around these elements by requiring that the client to deliver the hosting platform two weeks before you expect to need it, so that both timescales and platform shortfalls can be addressed.   Learning to recognise dependencies, assumptions and risk factors is an essential skill… brainstorm these with the team and ensure you’ve planned for them as far as possible.
8. Use plain English
   Yes, your specification is a technical document, but it’s also the document that outlines the agreement between you and the client as to what you’re going to deliver. You need your client to understand what’s in the document, and sign off against it – so baffling them with technical language is not going to get you any closer to a good clear understanding on both sides of what’s being delivered.
9. Have someone CHECK your SPEC for specificity and certainty
   Whether your spec document is authored by the project manager or the lead developer or a combination of the two, the key thing is to have it checked by someone else once it’s finished (and before it goes to the client!). Someone who hasn’t been involved in writing the spec should check it, actively looking for holes, unanswered questions, and undocumented assumptions. Anywhere where there is uncertainty, resulting in questions such as “will it do this?” and “how will that work” must be flagged and reviewed. For the spec to be fit for purpose on final check, you must be able to use it to create a solid agreement as to what is being delivered within the project cost, and to prevent scope creep. Can your spec do that?
10. Document change requests!
    Once your spec is complete and signed off, everyone needs to be clear on what happens when, inevitably, someone wants to change something.   Be clear in the spec that change requests will be documented, analysed, and costed – and implications on timescales and delivery discussed.
11. Remember to look for lessons learned
    It’s an old management training adage – but if you keep doing the same things, you’re going to get the same results. So, after each project, take time to review your planning and delivery. Did it come in on budget? Did the specification do its job? What lessons were learned?