The Ultimate Client Requirements Document in software development. Here’s the draft and story about how I thought of it
The Client Requirements Document (with Business Requirements Document (BRD) and Technical Requirements Document (TRD) aka the Software Requirements Specification (SRS)) is one of the main tools in software development. Throughout the community of project managers, software analysts, IT account managers, coding and testing engineers, pretty much everyone who earns a living from being a part of the process of software manufacturing, uses it constantly. Some of us write it from scratch, some amend and enhance it during different stages of the project, some use it as a guide and a reference for software development and testing.
Rafał Kołakowski, IT Manager and Project Manager at 3e Software House
As an IT manager I have led dozens of projects and have taken part in many more, in various companies, including organisations producing complex infrastructural software for government units. During the initial phases, as well as later and deeper into those projects I usually felt that my dialogue with the client was lacking something, namely a clear and concise structure along with a checklist that would assure myself, the client and all of the stakeholders that we hadn’t missed any important elements of the project, that could cause even minor distortions in the final product or allow it to go sideways from what client actually needed.
That’s how, and why a couple of years ago I started to build a template for a concise but comprehensive document, that would help me and all the stakeholders to have more control over the project, streamline the development and testing process and ensure knowledge continuity so as to avoid misunderstandings, dead ends and the reworking of some already finished features.
The template consists of 6 chapters that are supposed to be filled gradually during consecutive stages of the project preparation, from business analysis to the beginning of coding process. The chapters are as follows:
- Introduction (business purpose, description of current and changing process, technical description etc.)
- (optional) Description of the form fields
- Mock-ups
- User stories, acceptance criteria and testing scenarios
- Functional requirements
- Use case diagrams
I know enough and I want the template
What’s most important is that the document is built in a way that is multi-functional. It can be (and actually should be) the main reference point for developers, testers, graphics designers, product owners and the client. Having such a document brings numerous benefits:
- It helps to avoid chaos. All the necessary information is contained in a single document. There are no doubts and no vicious circles of emails - where have we put that information and which version is the correct one? Have we even done that?
- It is much easier and more effective to make changes to the project. Since all the specs, namely user stories, acceptance criteria, testing scenarios and mock-ups are in the same place, it’s much less problematic to modify all the parts of a project puzzle at the same time. When you have to modify a user story, or the acceptance criteria, you can modify accordingly the testing scenario at the same time – it is in the same table. A mock-up and the form field specs are also not very far away.
- The abovementioned advantage triggers the next very important one: there’s much less risk of inconsistency between different parts of the requirements analysis. This means - the document helps everyone concerned avoid the dangerous situation, when for example, the testing scenario doesn’t exactly match the acceptance criteria, causing a flawed application to hit the market.
- A well done Customer Requirements document can be used as a tender specification. Some may say it is not safe from a business perspective to produce such a detailed document at a relatively early stage of the project. I see it differently. When we produce such a detailed document it is usually highly appreciated by clients, and increases their overall evaluation of our work. I think developers should even encourage their clients to check the prices of competitors, using the Client Requirements Document they have provided. This way we show our openness and assure them, that they do not have to worry about possible vendor lock.
Importantly - the document should definitely cover only a single module, this means the building or upgrading of a single part of the application or system, covering a single, logical part of the business process - be it signing up to the application, placing an order, making a payment etc. If the scope of the project is limited, that it only includes a modification of a single feature, it can be described in a single requirements document. If the project is more complex it should be divided into a larger number of Client Requirement Documents, and each of them should contain information about how the changes done to a particular module influences the others, and how the changes made to the other applications influences that particular part of the system. Small applications can usually be described in about 10 requirement documents, the very complex ones may need a few hundred of them. Building the documents this way allows us to avoid any single document becoming too complex whilst at the same time ensuring the whole group of documents remains cohesive. All documents should have at least a two-part name, which allows all parties to easily identify which application and what particular part of it, the document refers to.
To prevent the emergence of wild copies of the document and to ensure no change to the document goes unnoticed, the document should have only one copy, kept in the repository of a project management application like Confluence or Google Docs that is used when working on the project. All changes to the document should be added in tracking mode and then the old copy should be replaced by the new one. Every stakeholder in the project should agree that only once changes are made to this copy, are they in effect.
The meaning of the Chapter 1 - Introduction - is rather obvious. It focuses on the description of the business background and justification of the planned feature. Importantly - all the points are relevant in new projects, when the software is developed from scratch as well as in advanced projects, when the essence of the project is modification and further development of features that have been released in the past. In the latter case, point 1.2 describes the current function of the part of the application that is going to be modified. In the first case it should describe the way the activities in question are currently carried out i.e. manually, or using another application, that is meant to be replaced.
When the document is a part of the larger whole (as mentioned above), consisting of a number of similar requirements documents it should also consist of at least one simple context diagram with a short description. It should depict project’s context among other systems and features, the major dependencies between them and most importantly, data transfers. The scheme should not be as complicated as full-blown data flow diagrams. It’s rather a view from above, allowing the reader to understand the role of the feature that’s being developed among other system components.
Despite its obviousness, the history of Chapter 1 (especially the Point 1.1 - Business purposes) is complicated. For a certain period I decided to cut it out, because of complaints from the team of developers. They stated that they were neither interested nor had the time to study the details of a client’s business - they just needed the user stories and acceptance criteria to get on with the work. After a few months I put this point back into the document, and now I’m 100% sure, that I won’t let it go away again. Firstly, from the strictly human point of view it is crucial for the whole development team to understand what the application in question is going to do. It is vital to reach a proper level of engagement and motivation - to know where we are heading, what our vision is, and what impact we seek to make on the market.
Secondly, this part is a very important reference with regards to future talks with client. During prolonged work on a project human beings tend to get distracted and partially forget, what the point of the whole project actually was. If this point’s content is evolving during the progress of the project, (which is perfectly fine in the agile approach) the summary of the original business goals is also a very important reference, to check how far we are from the preliminary vision, and how profoundly the evolving business needs should impact the application. In this part of the document, all the constraints that result from legal regulations and internal company procedures should be specified. This is also the right place to include - if they are relevant - the dependencies between our project and other applications used by the organisation.
The first element that I added to the document was Chapter 4 - Users stories and testing scenarios. This section contains the most important data, the description of functionalities that should be developed or changed during the project. Gathered together they should form a four-column table, similar to the example.
| Functionality | Title | User story | Acceptance criteria |
| Adding | Adding a shipment |
As a client I need to provide my address and the address of the addressee, print the label to be glued to the parcel and order a courier visit to the convenient time. |
|
| Adding a local shipment | As a client I want to provide an address of an addressee in Poland |
|
|
| Adding a European shipment | As a client I want to provide an address of an addressee on the European continent, but outside of Poland. |
|
|
| Adding an international shipment (outside Europe) | As a client I want to provide an address of an addressee in the country outside Europe |
|
In this section at least one type of a functionality named with a verb that describes the essential activity should be provided. The stories should be grouped in a way that each group represents a similar type of operations regarding their logic and place in the business process. This form of presentation allows us to describe the common parts of the user story and the common acceptance criteria at the beginning and then, in every user story we can describe only the criteria, which are specific to this particular story.
While the presence of user stories is obvious - they are the core documentation of every project - including testing scenarios, which is something that I thought up whilst talking to developers. They were complaining, that information included in the user stories is usually incomplete and disorganised and does not allow them to produce the features, that properly match client’s needs. During demo meetings clients usually found numerous discrepancies between the product and their vision. Of course the fact that they hadn’t precisely specified their vision earlier was no excuse for them. And they were right. It is our, developers’ job to squeeze all of the important information out of the client team before we start coding.
The provision of a complete set of user stories along with a list of testing scenarios is a very efficient way to overcome that problem. Testing scenarios should include all the necessary user journeys with a proper output from the application as specified with as many versions of these journeys as the number of acceptance criteria– specifically all the extreme values of user-provided variables.
Somebody may point out that preparing testing scenarios for all the provided user stories and acceptance criteria means producing an enormous amount of text. For example: If we have 30 user stories in the project, each of them having 5 acceptance criteria and two output types - positive and negative. This means, that we have 150 acceptance criteria and no less than 300 testing scenarios – meaning a 100 or more pages of text. That’s obviously too much, so we recommend producing testing scenarios in the form of a simple table containing different combinations of input and output data, including error messages.
Examle of a testing scenarios
| Name | Surname | Telephone | Address | Output | Message | ||
| John | Smith | +48503848555 | Warsaw, Al Ujazdowskie 5/6 | OK | Thank you for providing your data! | ||
| John | no data | +48503848555 | Warsaw, Al Ujazdowskie 5/6 | Error | Your “surname” field cannot be blank. | ||
| no data | no data | +48503848555 | Warsaw, Al Ujazdowskie 5/6 | Error |
Your “name” and “surname” fields cannot be blank |
.
.
.
.
etc.
In summary, in this way testing scenarios produce not only the material for the team of testers, but also a valuable reference guide for coders. They may learn from it, how an application should react for all the critical values provided by the user. An application written that way should work according to the client’s expectations - there is no space for any unexpected situations to emerge.
Well… there is. User stories plus testing scenarios are a perfect reference for describing backend functions. Things get tougher when we move to frontend and backoffice design. User stories can describe how the application should react, they cannot describe precisely what it should look like. When we work using only user stories and testing scenarios (even very precisely written ones), clients repeatedly complain about the way we arrange the elements on screen, about the order, size of different parts, about the fonts we used etc. We risk being confronted by a never-ending stream of questions saying “But where is ….”, or “But why does it look like that?”. Well, why? Because this is how the team of developers envisioned the application based on what it is supposed to do. Of course that kind of explanation never works for clients and we have to redesign user interfaces by trial and error, presenting consecutive iterations to our clients one after another. At that stage I understood, that to ensure smooth cooperation we need to expand project documentation to another chapter. This is Chapter 3 – Mock-ups and graphical design.
Working on mock-ups has numerous advantages. First - it prevents developers from producing an interface that the client won’t like. Second - drawing them is a perfect opportunity for the development team to think through client’s requirements and eventually find some inconsistencies within them. Third – just as important as the above - mock-ups work as a very efficient visual aid, helping clients to refresh their memories and notice that some features are missing, because they forgot to mention them whilst preparing the user stories and acceptance criteria. It’s much better and cheaper to hear a question like “But where’s something?” at the stage of the mock-up review than at the stage of development sprint review. Thanks to mock-ups many times we’ve avoided the situation, when client noticed a lack of some important features during the testing stage, forcing us to redo some already finished parts of the application. The more detailed the mock-ups - the better for you. They should show the whole screen of the user interface, not only the part that is going to be modified. The more information you include, like color codes, exact dimensions, fonts etc. - the fewer corrections you will have to make in the future.
The Chapter 2 – Description of the form fields is not my own invention. It is the answer to the important need of testing staff - how to find out if every single field in the application form is prepared, to only allow data that has the appropriate format and size, and its value fits into the anticipated range. By putting this point into the document we filled another important gap in the requirements gathering process. The proper values of each field are of course derived directly from that field function, but clients should take into account that the team of developers and testers aren’t always fully aware of their business constraints. They cannot always anticipate, that some data, that is correct from the mathematical or grammatical point of view could be incorrect for other reasons. When they are provided with the exact number of characters, character range (letters or digits or both), cross-dependencies between the fields or whether the content should be dictionary-checked or not, testers can work much more effectively, avoid asking a lot of unnecessary questions to the client and/or developers, and much more effectively search for the possible bugs.
Much has been discussed about what this document should contain, now is the time to say a few words about information that is optional or falls outside the scope of the document.
- The detailed specifications of REST or SOAP API operations. It is sufficient to include more general information such as what inquiries are needed and what data should be exchanged. Of course, where in the user stories this data is used and how it should be represented in the user interface, should also be included. No matter if we use a contrast-first approach (where we define the interface precisely before implementation, or the opposite contract-last approach the right place for a detailed specification is a Swagger document for REST APIs, or WSDL for SOAP.
- Non functional requirements, like how many simultaneous sessions the application should be able to cover, it’s response time, scalability, security requirements, numerous SLA requirements like availability, Mean Time To Repair etc. They should be put into the separate documents that are used in a process of environment and platform design. Of course they are extremely important, and shouldn’t be skipped.
- Last but not least - you should remember that the requirements document is not a user manual. The manual should be a separate and far more concise document, focused strictly on explaining the meaning of the features and examples of their usage during different business cases, skipping all unnecessary technical details.
- Data structures. The opinions with regards to including them in the User Requirements Document lack consensus. Some say, this specific architecture shouldn’t be put into the Client Requirements document since it is usually developed dynamically during the technical analysis and coding phase of the project. In practice it is beneficial to include a data model, even if it is preliminary one that will be later modified during the development process. Viewing the expected tables and fields is often a great eye opener for clients and helps them to realize requirements they haven’t thought about or (wrongly) have taken for granted. For example: should the address be stored in a single text string or divided into separate fields like street, house number, flat number etc. The first way is simpler but the second is much more error-proof and allows for much more sophisticated search and aggregation operations. Such decisions should be made at the beginning of the development process, because rearranging the database while the application is already up and running is a relatively complicated and expensive operation, and can generate many bugs. The preliminary data structure should be prepared by an analyst and audited by a database specialist or a developer possessing a substantial knowledge about database architecture, after the final acceptance of Customer Requirements. During the coding phase, all the necessary amendments to the data structures (i.e. the decision to split a single data table into several small ones) should be subsequently included in a separate document that should be treated as an attachment to Client Requirements.