10 June 2019 | Jack Fisher
At Pogo Studio we see our fair share of requirements documents, so we thought we’d offer our top tips for creating one. Writing a good requirements document can be a lot harder than it sounds. In fact, communicating what your business requires to an external team is often the culprit for things going wrong in the project lifecycle. Too often businesses find themselves in a situation where the project they set out to build and the finished product are leagues apart. So, what steps can you take to ensure that this doesn’t happen?
What is the requirements document?
Let’s start by examining what a requirements document is, and what it is used for. The requirements document should be one of the first steps in embarking upon a new digital project. The document should outline the details of what the software should do and how the user should interact with it. This includes what features it will have and what platforms it will run on. This document is then used as a reference point throughout the project. It’s how the software developers will know what to build and how you will know what they are building. For the purposes of this article, the example we will use will be an e-commerce website.
An e-commerce website exceeds the capabilities of a standard website which is designed to display information only. As you know, e-commerce allows users to purchase items, sign up for user accounts, receive emails, and much more. This means there is a lot more room for things to go wrong at the requirements gathering stage. So, what should be included in the requirements document?
What to include in a requirements document?
One of the first things to include in a requirements document is a short background of the company and the aims/goals for the project. This is a good place to define what a successful delivery of the project will look like. There’s no need to get bogged down in the details of the business at this stage, just a general overview will suffice.
Although there are no hard rules on what to include in the requirements document, we believe that a good second step is to cover the structure of the application. A good way to do this is to create a visual sitemap. A visual sitemap shows what pages will be on the website, and how the user will navigate through the pages. Think of it as the skeleton of the website’s menu, below is an example.
So, what is the Sitemap above showing? The sitemap should be read top-to-bottom starting with the homepage on the top level, then the main navigation links on level two, then the pages/content that sits beneath them. This gives a high-level overview of the structure the website will have. Creating a sitemap is a very useful exercise for both your own team and the team that will be developing the project. It forces all parties to properly consider what they are building and ensure that all the necessary details/functionalities are included.
An essential aspect of the requirements document is listing the core features of the software. This is sometimes referred to as the project scope. The simplest and quickest way to accomplish this is to write a bullet point list of all the features the software should include, although this could be expanded upon to create user journeys which provide further detail. Listing the core features can be difficult, as it’s not always obvious what needs to be mentioned and what goes without saying. For example, a core feature that would need to be outlined in an e-commerce website might be ‘the ability to apply discount vouchers to items'. Conversely, ‘the ability to see the products that are for sale’ might not need to be mentioned because it’s an obvious feature of an e-commerce website.
But here lies an issue, what is obvious to those writing the requirements document and those receiving the requirements document might not necessarily align. As a general rule, it’s best to air on the side of caution. It’s better to provide too much detail than not enough detail. You don’t want to end up in a situation where you’re being told: “you didn’t mention that in the requirements document, so we haven’t included it in the finished product”.
You might be wondering at this point how you can be expected to know what to include in a requirements document and what to leave out. We would argue that if you’ve never written a requirements document before, you can’t be expected to know all this information. That is why we believe any good contractor or agency will work closely with their client to create the requirements document. This approach will always lead to a greater chance of a successful project. We believe that it’s best to include the people delivering the project at as early a stage as possible within the project lifecycle. The software developers can then help guide your requirements, by asking the right questions they can help you figure out what is possible, what is necessary, and what is essential.
One final point we would like to touch upon is that the requirements for the project may change during the development of the project. This is the case for almost every digital project. For this reason, you might not believe that a requirements document is necessary. What’s the point in spending time writing a detailed list of requirements if those requirements are only going to change further down the line? You wouldn’t be alone in holding this opinion, but we believe that the requirements document still holds value, even if it’s anticipated that those requirements may change. The requirements document can be a flexible document that adapts as requirements adapt.