The Ultimate Client Requirements Document in software development
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 organizations 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 the coding process. The chapters are as follows:
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:
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 influence 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 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 a 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 the 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.
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.
In this section at least one type of 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 operation 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 disorganized and does not allow them to produce the features, that properly match the 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 has 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 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.
Example of a testing scenarios
Your “name” and “surname” fields cannot be blank
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 to 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 the 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 the 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 the 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.
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 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.
