Ask any group of software developers their pet peeve, and you can guarantee the topic of poorly written user requirements specifications will make an appearance. After all, no one wants to begin a project unsure of exactly what the client is looking for. A thoughtful and well-written user requirements specification saves time and money, and ensures everyone is singing from the same hymn sheet.
To put it plainly: the better the user requirements specification, the better the outcome. This is a thought well worth keeping in mind as you embark on your project.
What is a user requirements specification (URS)?
In software engineering or systems design, a URS is a planning document that specifies what the software or system needs to do. It is written from the point of view of the end user and does not need to be technical or complicated. According to Intersys MD Matthew Geyman, “A well-written URS is clear, unambiguous, well explained and concise. It helps the systems designer or software engineer fully understand a client’s needs, and can be used to plan a timetable, estimate costs and so on.”
It’s a mantra that we follow rigorously when embarking on our numerous software development projects such as our proprietary supply chain risk software for complex, multi-stage supply chains, SCAIR®.
Note: this is a separate document to the functional or software specification. These are documents produced by the software developer that specify how the requirements in the URS will be met.
Why it’s important to get it right
A poorly-written URS with vague requirements and ambiguous language can lead to confusion between the client and the provider. In some cases it leads to the need for extensive reworking, which in turn can lead to blown budgets and broken deadlines. “A detailed and explicit spec reduces unknowns and produces tighter quotes, as well as better outcomes,” says Matthew.
When creating a URS, there are two things to consider: what to include in the document and how to write it.
What to include
The exact information that needs to be included will vary from project to project. Evidently, a complex project will have more requirements than a simple one. However, there are some fundamental principles and important features that amount to good practice for most projects, regardless of size.
Authors
It is a good idea to begin with a list of the people responsible for creating the user requirements specification. This should include the name, job title, date and signature of everyone who co-authored it. Having all responsible stakeholders ‘sign off’ on the URS ensures that all those involved are clear that the document has been approved.
Introduction
This can be brief. The most important things to include are who you are and why the need for this URS has arisen. It might be helpful to give a very brief background of the company. For example, [Company Name] is a start-up organisation based in the south west of England. We wish to develop a software app that helps hikers and walkers find trails and pathways in their local area. This user requirements specification (URS) documents the user requirements for the development of the app.
Objective
A good objective clearly describes the goal of the project in non-technical terms.
This should give a brief overview of the project, in non-technical terms. It should be written in a narrative or descriptive style (ie not a checklist or abbreviated language), and outline what the product is intended to do. To assist with writing this section, ask the following questions:
- What am I trying to achieve?
- What problems will this product solve?
- How will it streamline or improve the existing system, or similar product in the marketplace (if one exists)?
In the case of the hiking app example above, it might be something like this: “Our goal is to create an app for both iOS and Android phones that guides walkers and hikers to trails in their immediate vicinity. The app should allow users to create profiles, upload photos, design trails and write reviews. Existing hiking apps often include information that is out of date and/or unverified. By allowing users to update trail information, they will collectively have more reliable data with respect to the condition of a given trail at any given time.”
Requirements
This is the most important part of the URS. Take each requirement one at a time, ensuring that it is precisely described. Remember, you should write this in narrative form, focusing on what the product should do, rather than how it should do it. Continuing with the hiking app example, a requirement might be: “I’d like the Welcome screen to include a link to the user’s profile, as well as links to completed trails and suggested trails.”
It is good practice to number each requirement and also to indicate whether it is high, medium or low priority.
Think about:
- The impact expected
- What you want to happen at each point
- What different users would expect to see. For example, ‘As an admin, I would expect to see …’ or ‘As an end user of the app, I would expect to see…’
Supporting documents
For some projects, supporting documentation may be appropriate. This may include:
- Images, sketches or mock-ups of concepts central to the project, such as user interfaces
- Examples of software and systems that already fulfil some of the requirements you’d like incorporated
- A site map (for a website)
- End-user personas
Glossary
If your document uses technical or non-technical jargon, abbreviations or acronyms, make sure to explain them clearly here.
Index
If your document is particularly long, consider including an index at the end.
How to write it
The above section outlines what you should include in your document. What follows are some notes on describing your requirements clearly. Don’t see these as ‘style points’ or ‘the icing on the cake’. Ambiguity is the enemy of project success and expressing yourself precisely is vital: your developer will thank you for communicating in an unambiguous way, and you’re likely to be far happier with the end results too.
1. Use SMART targets
- Specific
- Measurable
- Achievable
- Realistic
- Time-bound
SMART targets provide a good way to ensure your user requirements specification is well-defined and verifiable.
Specific: Your requirements should be clear and specific. For example, rather than drafting a vague requirement such as ‘improve ad latency’, think ‘reduce ad latency by 50%’.
Measurable: To be measurable, a requirement must state something that can be confirmed by examination, test, or demonstration. Avoid subjective statements such as ‘easy’ or ‘faster’. If it can’t be measured, there’s no way for both parties to agree that the requirement has been met.
Achievable: Your objective needs to technically feasible. If you’re not sure whether something is technically possible, further research is needed. If you’re still not certain, word what you want as a ‘goal’ rather than as a ‘requirement’.
Realistic: Even if something is technically achievable, it may not be realistic due to budget constraints, time restrictions, regulatory requirements or other limitations. It’s important to be realistic when determining your requirements.
Time-bound: What is the time-frame for the project?
2. Avoid ambiguity
A user requirements specification should be clearly written, using simple sentences, and without ambiguity. Examples of ambiguous words are:
- improve
- fast
- slow
- user-friendly
- easy
- sufficient
What exactly is meant by user-friendly or sufficient? These terms are subjective and therefore impossible to measure.
Similarly, avoid acronyms, abbreviations and jargon as they may lead to confusion.
3. Take one requirement at a time
This makes it easier for everyone to see how each requirement has been developed and tested.
4. Prioritise
Think carefully about word choice. Words such as ‘shall’ and ‘will’ typically define requirements. They imply that the requirement must be met. Words like ‘may’ and ‘could’ define goals that are desirable but not necessarily required. Do not confuse these terms, and make sure you use them consistently in your document.
Following these general guidelines will help ensure that your brief is clear and concise. We will follow up this post with a full user requirement specification template, which you can use when working with Intersys or any other software developer.
Intersys designs bespoke software for a wide range of sectors including life sciences, legal, education, renewables, TV and media, and many more.
Find out more about our software development services or get in touch now to start a conversation.