Seven ways to write better project specifications

Written by Vineeta G - October 28, 2019

Project specifications play an important role in the success of your project. While every project manager will be aware of this, it is important to know how to write one that is effective, how best to get clients to collaborate, and how to formalise the agreement. 

What should your project spec contain?

Think of the project spec as a blueprint for your project. It should give a full outline of the project scope, deliverables and deadlines. 

The project specification explains what each part of the website is going to do, and why. Use cases should be provided to clearly explain how users will interact with different templates and blocks. It should also contain detailed information on integrations, as well as the detail of any risks associated with the project. 

Who is the project specification for?

The project spec is relevant for all stakeholders within the project, for a variety of reasons.

  • For project managers, it functions as a ‘one source of truth’ document, a place where they can add all notes relating to the functionality
  • For developers, the spec is an instructional guide of what they are going to build and why
  • For clients, the project spec is an agreement of what they can expect from the final product
  • For testers, the spec is a clear indication of how the site should function, so they don’t need to question whether something is behaving as it should
  • New team members can be easily brought up to speed on a project, whether they are client-side or in your own organisation. All they need to do is read the spec!

Here are seven ways to write better project specifications:

1. Include use cases

Use cases are important not only so that a developer understands what functionality to build, but also because it refocuses us on the project’s desired outcome. 

It’s not a collection of to-dos for developers, it is a document explaining what needs to be done and why. Think of it as how the product functions, but in human language. This is essential for making the connection with the end user and understanding how they are going to interact with the product. 

2. Project specifications should be neatly organised

You should make sure the spec is easy to read. Start off with an introduction and divide the content into logical sections. Include a table of contents so that readers can easily find the parts that they are looking for in the future.

3. Make it a living document

It is unrealistic to expect to complete the spec at the very beginning of the project. As requirements change and develop it will need to be updated regularly. You should aim to have it up to date at all times and ensure nothing is missing by the time development starts. 

However, as a project manager you also need to ensure that the client is made aware of any updates. Which brings me to my next point…

4. Make it a formal document

In my opinion, the process of signing off your project specification with the client should be a formalised process. During the initial planning stages of a project, there will be lots of meetings, phone calls and documentation being shared around. You don’t want your project specification to become just another document that is glanced at but not properly understood. 

I suggest that once you have finished writing the spec and your client has had a chance to review and feedback, that you create a PDF and send it to the client asking for sign off. You could also do this using something like DocuSign. This should flag to the client that the project spec is the agreement of what will be delivered and they should read it carefully. 

Of course, if it needs to be amended at any point, this can be done, but the amended version should be signed off too!

5. Include statements on your rationale

Projects can be long winded – depending on the scope and project delays, it could be six months or even a year before a project is off the ground. It is important not only to keep track of what decisions were made but also why they were made. 

Include detail where needed on why a certain direction has been taken or why the proposed solution may be the only one that works for this project. This will be very valuable not only during the project but also in the future if you need to quickly dive in and discern why certain decisions were made. 

6. Know when to write one

This is something you will need to judge on a case by case basis. Almost two decades ago, the software developer and Trello creator Joel Spolsky wrote that any project that requires over a week of coding work would suffer without a fully defined spec. I would be inclined to agree with him. 

You don’t need a spec for every single project, so make this judgement based on the timeline and budget available. 

7. Involve your team

The project manager should be responsible for the creation and overall ownership of the project spec, but don’t be too guarded. Make sure the team’s designers and developers collaborate to make sure the spec is as detailed as possible, with detailed technical information when needed. 

In summary

It is important to remember that project specifications are not a waste of time. They may take time to write, but this is an investment. All in all, what you put into creating your project specification will save you time in the long run.

Your specs will vary from project to project, but don’t be overly concerned with making it perfect. The most important thing you need to ensure is that nothing is missing when it comes to the agreed functionality of the end product, so that both you and the client are on the same page.