One Requirements Document Template to Rule Them All

With the advent of Agile methodologies, we have (rightly) come to believe strongly in ‘Working Software over Comprehensive Documentation’. Everything you need to know to create a winning requirements document template. Create all types of requirements templates such as simple, functional, business & software etc.

Truly enough, from experience I can tell you that Agile ways of working bring about more success per unit of work than Waterfall ever managed. Then again, and I have said this before, working Agile doesn’t imply NO documentation.

With Agile, the efforts to document (Requirements, Design, Solution) are optimised to a point where you’re ideally only spending the absolute minimum time necessary at any given point in time to document. But you do spend time on documentation.

“Working Agile doesn’t imply NO documentation.”

In this blog post, we’ll discuss the minimum information you need to capture in a Requirements Document, and a basic template for how you can go about this. We’ll also consider how and why project requirements documentation help, and whether you need a template for Agile projects.

Before we begin, however…

What does Requirements Documentation mean?

It can mean different things to different people, teams, projects, methodologies. Your employer and your industry can also dictate what and how much Requirements Documentation you need on your IT projects.

If you’re following Agile, Requirements Documentation is pretty much equal to your Product Backlog, Release Backlog and Sprint Backlogs.

If you’re following Waterfall, on the other hand, this could be a Business Requirements Document (BRD) template.

Why is Requirements Documentation necessary?

For instance, Internal audit teams and external regulators require that comprehensive documentation be made available to them for reviewing IT systems changes. This is so they can check and ensure systems are built to a standard, and prevent any fraudulent activities.

Attrition and role changes are a phenomenon common to any team, department, company. You want a way to create a permanent knowledge store of any systems or product knowledge that your team have gathered during an IT project, lest they leave for a better opportunity and take that knowledge with them.

During the delivery of an IT project, various stakeholders – including developers, testers, legal and compliance teams – need access to comprehensive requirements documentation to fulfil their delivery commitments and ensure requirements traceability.

Developers and testers need to know ‘What is the requirement?’ for all high level and low level queries they have during development. Even on Agile projects, maintaining a sprint-level backlog with user stories and detailed acceptance criteria helps the Scrum team deliver to exact specifications.

There are more reasons – but you get the drift. Agile or not, Requirements need to be documented.

When and how often do you update the Requirements document?

On projects following Waterfall methodology, Requirements are finalised and signed-off before Design and Delivery can begin. So, you don’t update the Requirements document frequently. Change control kicks in after requirements sign-off to handle Change Requests.

On projects following Agile methodology, Requirements are a living document. Whatever the medium you use to maintain them, Requirements are constantly updated during Sprints. Sign-off is usually implicit when the Product Owner approves the deliverables at the end of a Sprint (the Demo meeting).

“On projects following Agile methodology, Requirements are a living document.”

Requirements Document Example

A requirements document outlines the purpose of a product or software, who will use it, and how it works. This document should be used as a starting point for all projects, before the design and development stages.

The requirements document should be simple and detail only the features included in the first version of the software – even if you plan to expand and add more features in the future.

The main components of a project requirements document include:

1. Executive summary
2. Purpose and Scope
3. Goals
4. Target Market Overview
5. Product/software Overview and Uses
6. Requirements (technical, environmental, functional, support requirements, etc.)
7. Constraints
8. Workflow
9. Evaluation Plan and Performance Metrics
10. Future Work

The goal of the requirements document is to make sure that everyone understands the software and how it works so that they can work toward achieving the same goal of delivering a quality product.

Is there really One Requirements document template that rules them all?

No. Different companies, and even departments within companies, use different requirements documentation templates – dependent on their specific internal and external stakeholders, technology and systems involved, and a host of other factors.

And Yes. Whatever the template, a core set of key information is contained in each. And whatever the methodology or terminology being used, this information set remains central to any Requirements template.

Any form of documentation that helps you gain agreement among the team about the scope for a project, and supports information requests from other internal, external stakeholders, is good enough as a Requirements template.

With that, let’s look at the core information set that every Requirements document should contain.

An Ideal Requirements Document Template

Note that what follows is a view of the minimum information that any Requirements Document should cover. In that sense, yes, I provide you with a template.

As with any template, chop and change to suit your specific team, system, technology, methodology, organisational requirements.

Specifically, you can use this minimum information set to create a ‘reportable’ template for both Waterfall and Agile projects.

Revision Log

This section is one of the first that you see in a product Requirements Document template. It explains what has changed between two versions of the document, and who has made these changes.

The revision log is primarily a Waterfall project staple; it has less meaning on Agile projects where requirements can (technically) change all the time.

A revision log usually includes:

• Version number – identifies the iteration number of the current version.
• Updated by – who made the changes
• Reviewed by – who reviewed the changes
• Version description (optional) e.g. first draft, second draft, final draft, signed-off etc.
• Change description – high level description of the changes introduced in this version of the document.

Overview

Introduce the project and its background – the why, what, how, who and when. This section helps set a context for the project, and ideally references its underlying business case (where one exists).

The Overview is key for your intended audience to understand why you have chosen to deliver this project, be it an enhancement or new system development.

You can highlight the major business and other goals you intend to achieve by delivering this project, target users/customers who will benefit from it, and key functionality that target users will receive access to.

Scope

Key sub-sections: In Scope and Out of Scope.

The Scope section describes the major functional and non-functional Scope for the project, enhancement, initiative.

“We cannot hope to mitigate or resolve every risk or issue before delivery can begin. So, it is important to document any known Risks, Issues or Dependencies (RID). “

Ideally, this will be represented as a set of high level bullet points that correspond to high level requirements.

Each bullet Requirement here will or should have a corresponding set of detailed Requirements elsewhere within or outside the document.

As the name implies, Out of Scope sub-section explains what will NOT be delivered by this project, and (usually) why. This is important to manage expectations of your stakeholders (assumptions about scope are, as you will be aware, a major source of heartburn during implementation sign-off).

On Agile projects, high level requirements usually correspond to Epics and the big User stories that make up these epics.

For most non-project stakeholders, the Overview and Scope sections provide sufficient information about the project so it is important to be both concise and precise at the same time.

Assumptions, Risks, Issues and Dependencies

No project undertaking is without its knowns and unknowns. We cannot hope to mitigate or resolve every risk or issue before delivery can begin. So, it is important to document any known Risks, Issues or Dependencies (RID).

With each known RID, make sure to identify a path to resolution that could help mitigate or resolve it. On Waterfall projects, this is called ‘Path to Green’ – i.e., what you need to do to get your project back to Green or On Track status. Risks, Issues and Dependencies arise throughout the lifecycle of a project.

“For most non-project stakeholders, the Overview and Scope sections provide sufficient information about the project so it is important to be both concise and precise at the same time.”

Usually, medium to large corporations maintain an online RID tracker linked to a project on a tool such as Clarity. On Agile projects, RIDs can be logged and tracked using Impediments and with dependency links being established between the affected story/task/activity and the impeding story/task/activity.

Documenting Assumptions helps highlight where you’re working with a blind spot about a requirement, system area etc. Sometimes assumptions include aspects like resource availability from a particular team that are external to your project and may not follow similar planning practices.

For instance, if you’re working on the mobile app development team and need support from a backend development team to provide a data feed for your project, it’s quite possible that your team follow Agile and the backend team follow a different methodology. This could mean they aren’t going to support your Sprints, and you may need to plan in their support for a specific time and duration.

The assumption here is that the back-end team will be available during the agreed timeframe and not be pulled into other higher priority or urgent work. And the risk is that they may not be able to support your project as agreed.

Requirements

Document the requirements that your Business Sponsor or Product Owner need to be delivered by this project/initiative. Requirements can be classified under several headers – the internet provides a variety of responses for the search string ‘types of requirements’. What we need is a standard format that you can use to document all requirements.

“Documenting Assumptions helps highlight where you’re working with a blind spot about a requirement, system area etc.”

On Waterfall and Agile projects alike, your company may dictate you follow certain naming and numbering standards for requirements.

A cookie cutter format for documenting requirements would be:

• Index – can start from 1, 2, 3… for high level requirements and go on to 1.1, 1.2, 1.1.1, 1.1.2 and so on for lower level requirements. You can apply such numbering conventions to Agile user stories as well.
• Title – brief description of the high-level requirement. In Agile, these could be the descriptions for Epics.
• Detailed Description – self-explanatory. User stories in the form of ‘As a customer, I can… so that…’ fit here.
• Owner – usually the Business Sponsor or the Product Owner. Can also be stakeholders like IT, Marketing, Legal, Compliance etc. depending on the requirement.
• Priority – High, Medium, Low (or a variation of this)
• Deliver By – is there a specific desire to deliver this requirement by a date? There could be business-driven or compliance-driven considerations that dictate the desired delivery date for a requirement.

Non-Functional Requirements

Usually, Non Functional Requirements (NFRs) find their own section in a Requirements Document template. If you are familiar with this topic, you’ve heard about Performance, Reliability, Scalability, Maintainability etc.

Why do they have their own sections? This is because NFRs are often stated in measurable terms, and hence need to be stated differently to other requirements.

For example: when a customer logs on to the mobile app, logon should complete and dashboard should load in less than 2 seconds; the system should never go offline, except for scheduled maintenance periods, etc.

Note: it is possible to follow the Agile user story structure (‘As a customer…’) for NFRs too.

Links and References

This section provides references and links to documents and material that provide more context or supplement the Requirements Document.

On Agile projects, you can provide links to the Dashboard, Product Backlog and other Agile artefacts.

On Waterfall projects, you can provide links to the Change Requests Log (link?), and other related artefacts.

In general, Business case, Architecture and Design documents, supporting Regulatory documents and links, underlying business and marketing documents all find a place in this section.

Glossary

Add a Glossary of technical and non-technical terms that need defining to add clarity to the document. The likes of NFR, BRD, iOS, MacOS, GCM etc. find a place and a description here.

The glossary benefits stakeholders and project team members that may not understand all the terminology and acronyms being used in the Requirements Document.

My team use Agile methodologies; do I need this template?

That depends. I’ve worked with clients who used Agile methodologies for project delivery, and yet had to maintain a BRD or Scope document to meet their Regulators’ expectations.

In other cases, Audit, Compliance and Legal teams have insisted on seeing a physical document that is specifically dated. As you can see, while we may have come a long way with Agile, there are some pressing real life needs that still need to be addressed with practical solutions.

So, I have recommended to such clients that they should simply extract the Product Backlog (or Release Backlog if your Product Backlog spans multiple releases), and insert it in place of the Requirements and Non-functional Requirements.

With this approach, you can generate a Requirements Document that meets your stakeholders’ expectations at any time – in a matter of a few minutes to an hour. Considering the benefits involved, I’d say this is time well spent.

---

Now It’s Your Turn

Your unique project, team, organisational situation will dictate what other sections you need on a Requirements Document template. The information above is intended to get you started on the most fundamental information set any Requirements Document should cover, and I hope you find it useful.

Remember to always prioritise progress over documentation. But then again, remember that documenting knowledge of a project, product, system is essential to ensure business continuity and future project success.

What other information do you think needs to be captured to make this a truly singular template that rules them all? Comment below, and let’s have a healthy discussion!