How and When to Write a Requirements Document
A common perception is that projects need a "requirements document", but it's not always clear what that means, or what a requirements document should include. What if you're trying to be "Agile"? Doesn't that mean you don't need a requirements document in the first place? Is a requirements document a "contract" that must be followed to the letter? What happens if requirements change after it's written?
These are good questions, and they point to the fact that requirements documents are anything but foolproof. In the wrong circumstances, and used the wrong way, a requirements document can hurt more than it helps. However, in the right circumstances, and used in a sensible way, a requirements document can be useful. How do we make the distinction?
The most common problem with a requirements document is that it promotes the wrong behavior and the wrong way of thinking about requirements. That's right. We often confuse the issue because we think a requirements document is about "documentation", which seems necessary. However, there's more to it.
First of all, it's not really that practical to put all the requirements for a project into a single document. I know that doesn't stop people from trying; I'm just saying it's not that practical. The reason is because good requirements typically consist of many different artifacts. On a typical project you may need wireframes, copy decks, spreadsheets of tabular data, architecture diagrams, workflow diagrams, checklists, test scripts, and other forms of specialized documentation to capture all the requirements, especially the more detailed ones. If I use one, I find it is more practical to keep a requirements document to"high level" requirements, and supplement it with supporting artifacts as needed.
As soon as you decide to put things into a document, however, you need to be wary of a much bigger problem. That is the danger of a requirement documents being used as a substitute for conversation, collaboration, and participation. This will almost always set up a project for problems.
If you rely on written documentation as your sole means of distributing requirements, you will invariably end up with various interpretations of what they mean. This will be true even if you pour endless hours into writing super-detailed requirements; a short conversation will always beat it when it comes to getting people on the same page. There will almost always be questions, or things that people did not quite understand. There will be things that people overlooked or didn't read, which can be called out in conversation. How many people do you know thoroughly read instruction manuals? I think it's a similar number that thoroughly read requirements documents--i.e. less than ideal.
Furthermore, requirements are a team effort, not the sole responsibility of a single person deemed to be the writer of the "requirements document". You need the Product Owner to define priorities; stakeholders and subject matter experts to explain how the business rules should work; project managers and business analysts to identify dependencies; developers to estimate, vet solutions for feasibility, and give technical recommendations; UX designers to identify user interface considerations; testers to point out data needs and edge case scenarios; and so on and so forth.
The moral of the story is a requirements document does not mean that one person comes up with the requirements and documents them for everybody else to read and execute. Creating requirements is a team sport. The document is just a form of written memory of what was discussed and what the team came up with, and in that sense, can function as a useful reference.
Finally, we must be careful of thinking that things are "set in stone" once we write them down. Again, this is not what the requirements document is for. A requirements document must typically be refined and revised many times because requirements change, are refined, and emerge over time. Keeping a requirements document means committing to updating and versioning that document as necessary. A requirements document may ironically facilitate more revisions and changes. This is because every time we re-read the document, it is not unusual to identify some small detail we missed, or to have a new thought that impels us to take the requirements in a new or slightly different direction (this is not always a bad thing).
Given the above challenges, however, it is no mystery why some prefer to dispense with a requirements document altogether. And the truth is, you may be able to get on fine without one.
As I explained in A Short Guide to Writing Software Requirements, I recommend User Stories as the starting point for requirements. You can put User Stories into a "document", but you don't have to. You can just as well put User Stories on note cards, or into one of the many Agile software programs now available. This is often better than a document. Note cards can be easily moved around or re-organized. Software programs allow you to add attachments, make easy edits, drag and drop user stories into iterations, add tasks directly to stories, and so on. This can be a lot more effective and productive than keeping up a document which takes special effort to format, edit, and re-distribute over and over.
So why use a document? It makes sense if it is the only practical alternative. There are times when it is, due to circumstance. For example:
You may be given no budget or authorization to buy or subscribe to a good software program
The requirements have to be reviewed by stakeholders who are remote or not available to be closely involved with the project team.
You have a client/vendor relationship with the stakeholders, and documentation is necessary for accounting purposes.
You have an internal "sign off" process that requires documentation to review.
Awareness of the context surrounding the project is uneven, due to not everyone being in the loop or in the same conversations.
These are not ideal situations, but they happen. Improve on things where you can. First, try to "nip in the bud" the behavioral problems I discussed above with a requirements document. Focus on collaboration, discussion, and understanding that requirements tend to emerge over time and are a work in progress.
Try to further gain acceptance for requirements being a collection of artifacts rather than a single one. This is far preferable than trying to insert many different artifacts and independent files into a single document. You will spend more time struggling to assemble and update the requirements document this way than you will actually getting any work done. For very simple projects, the best way to express the requirements might be in an alternative format, such as a wireframe, protoype, or diagram, negating the need for a "document" altogether. The most important question is "do we understand what it is we need to do?", vs "do we have a requirements document that looks a certain way".
Assuming a more complex project, and the need for User Stories, I often prefer to maintain them in a spreadsheet, which allows for easy updating. I can insert, delete, and re-order rows in the spreadsheet to make updating Conditions of Satisfaction easier. To re-order User Stories, I can put them on different tabs and then drag and drop the order. Then when I'm ready to produce the final document, I copy the tables from the spreadsheet and insert them. It is the most manageable way I've found to document User Stories if I need to use conventional tools such as Microsoft Word and Excel. The result looks like this:
Since I'm using Microsoft Excel here, I might as well take advantage of things it does well. I use the automatic alternate shading to make things readable; I use indenting to group things together; and I use auto-numbering to create an "index" to make it easier to refer to things within the document. For example, if I need to refer to a specific Condition of Satisfaction tied to a specific User Story, I can say please see item "4.3", or in other words, Condition #3 under Story #4.
If we're going to create a requirements document, however, I am more concerned with the last reason I said you may need one--for "awareness of context". This is vitally important. All too often, we focus on the details too soon, without taking the time to understand the rationale or background behind our objectives.
A useful requirements document should convey this context. Ideally this is something that is a topic of conversation that includes everyone, but putting this into a requirements document actually makes sense, as a reminder, to ensure everyone is on the same page, and to help transition in new people to a project, when necessary.
In other words, if I come in as a complete outsider to your project, your organization, and even your industry, I should be able to, from reading your requirements document, at least get a decent idea of what you are trying to achieve.
Let's review what some of these context-oriented topics might be. Note that I don't believe in a rigid template for a requirements document; include what is relevant and valuable, and discard anything that is unnecessary or already evident. User Stories, as helpful as they are, are far from the end-all and be-all in terms of understanding a project. Consider the following "sections" to include in your document:
User Definition/Analysis
Who exactly are the "Users" referenced in the User Stories? In detail? What are their backgrounds, their demographics, their needs, their responsibilities, their working process, and so forth? The better we understand the user, the better job we can do with requirements. For example, you might specify a definition like this:
Widget Buyer: The typical widget buyer is between the ages of 50 to 65 and skews 65% female to 35% male. They are typically college-educated and in the middle- to upper-income brackets. They view the widget as a major investment decision and will generally prioritize quality and features over price. They take significant time to make their buying decision, often weeks, and do considerable research beforehand. This user is interesting in reading detailed information on product quality and features, as well as comparisons to competitive products. This slightly older demographic responds well to an uncluttered user interface that is easy to read and use without the requiring great visual or motor acuity. They also prefer simplicity of design and a short learning curve vs. many extra features.
Understanding the context behind the user is helpful not only for thinking through requirements, but for increasing project engagement as well. The more "real" we can make the user in everyone's minds, the easier it is to understand why the project is important and what needs have to be met.
Now, let's take a few steps back. When it comes to understanding context, there are even higher-level topics that are critical. Consider including sections on the following:
Project Overview and Objectives
What is the project fundamentally about? Why are we doing it? What is the business problem we're trying to solve, or the Return on Investment that we're after?
Schedule and Constraints
What are the important deadlines that need to be met? What is driving them? What constraints do we have to deal with in terms of time or resources, and why?
Assumptions
What key assumptions are driving the project? What are the assumed roles and responsibilities? What are the assumed resources or assets that will be available? What are the assumed turnaround times for reviews and approval? What are the assumed conditions under which the project objectives apply?
Dependencies
What dependencies are critical to the requirements or their implementation? What is the impact of a change in one or more of the dependencies? How will they impact the schedule, scope of the requirements, and so on?
Goals for the Minimum Viable Product
What is the minimum we initially need to achieve to have a product worth getting out the door?
Non-Functional Requirements
What non-functional requirements do we have in terms of performance, scalability, security, compatibility, and so forth?
Brand and Creative Requirements
What requirements do we need to adhere to around our brand image? What styles, imagery, tone, or values do we need to express?
Content Requirements
What supporting content do we need in terms of manuals, FAQs, context-aware help, tooltips, captions, descriptions, labels, searches, indexes, etc.?
Legal and Compliance Requirements
What operational, accessibility, transparency, privacy, or other regulatory policies do we need to comply with?
Marketing Requirements
What requirements do we have around search engine optimization, distribution channels, metrics, campaign tracking, data collection, analytics, and other measures that are marketing-related?
Administration Requirements
What things do we want to be able to self-administrate vs. having to go to a developer to perform? What do want to be able to edit or update in terms of content, data, users, or business rules?
Infrastructure Requirements
Are there specific hardware, network, platform, or technology stack requirements that our solution needs to support or be compatible with?
Integration Requirements
What existing systems or software do we need to integrate with, such as databases, CRMs, ERPs, third-party services, and so on? What external data do we need to consume, or what internal data do we need to expose to other sources?
Training and Documentation Requirements
What post-project documentation do we require? What do we want documented in terms of how the solution works? What training documentation do we want for users? For administrators? For new developers?
Maintenance Requirements
What are the expectations for how the end product will be maintained? Who will be responsible for maintenance? What types of updates may be necessary? At what expected intervals? What "behind-the-scenes" maintenance may be required?
Out of Scope
Last, but not least, what will we NOT do as part of the project? What is outside of the project goals or product vision even if it easy to do or we are technically capable of doing it? What will we deliberately avoid in order to focus on more valuable items? Note that this last section may exist on its own, or you might find it helpful add it to each of the previous sections we've discussed.
Surprised at the long list of possible topics? This may be the case if you're under the impression that requirements mainly consist of "User Stories". In fact, requirements consist of a rich context that surrounds them. If you already understand this context and it has been well communicated to your team, then great. You may be able to skip this and can dive straight away into User Stories. More often than not, however, I've found it's a good idea document some of this for reference. If you're going to create a "Requirements Document", I believe this to be worthwhile content for it.