Concise requirements give your team a useful, easy to read and easy to change understanding of what must be done. Great requirements exist to do three things:
- Identify the problems that need to be solved.
- Explain why those problems are worth solving.
- Define when those problems are solved.
Concise Requirements – Revisiting
In the three years since we last looked at Writing Concise Requirements from the Big Ten Rules of Writing Requirements, the iPod evolved to give us a better experience. Let’s see if we can do the same with the topic of brevity in requirements. The size of our community here has grown ten-fold, and the people who were here back then have grown just as much. It makes sense to look at this again.
Writing concise requirements is not just minimizing the number of words you use. Writing concise requirements is presenting the most important information in the easiest format for your audience to consume.
Concise Requirements Identify the Problems That Need to be Solved
Ultimately, requirements are the problems that we choose to solve. A concise requirements artifact (formal document, index card, photo of a whiteboard, whatever) is one that has the highest signal-to-noise ratio possible. You’re maximizing the amount of communication, and minimizing the cost of communicating.
You want your requirements document to read like the lines, not the points. If the line (the signal) is what you really want, and you communicate a big pile of points (the signal, hidden in the noise), you run the very real risk that your audience will misinterpret the signal.
User stories provide the best example of clarity that comes from conciseness. The format you should use, based on Mike Cohn’s great book, User Stories Applied, is
As a [role], I want to [do something] [with some frequency] so that I can/will [achieve some goal]
The user story is not always the right communication format – it depends on what problems you’re solving, and who is on your team. Sometimes, use cases work better than user stories. Conciseness is important for use cases too. Start with a good use case name.
Concise Requirements Explain Why Those Problems Are Worth Solving
Last week’s article on Valuable Requirements focused on why particular problems should be solved. Your focus should be on value, and that article discussed five ways to assure that your requirements are valuable. One of the techniques, the use of an Ishikawa diagram, provides a method for identifying the root causes of problems.
Imagine that you have a collection of user stories, representing problems to be solved for your users. You need a way to demonstrate why this user story should be implemented and why that one shouldn’t. You can often use the Ishikawa diagram in the same way. A particular goal is achieved when a user is able to do something. Perhaps several somethings are required. The point is that you can use the Ishikawa to drive home the point – if this set of user stories are all implemented, then this goal will be achieved.
There are two reasons this is important – first, you’re providing context for your team. They understand why they are doing something. Second, you can make changes easily, because you can see the impact of those changes. By understanding the cause-and-effect relationships between problems and their values (user stories and their goals), you can see the impact of changing one or the other.
Concise Requirements Define When Those Problems Are Solved
Clarity is the goal of conciseness. It isn’t enough to say “work on this.” It’s important to know why you’re working on it, but that still isn’t enough. You have to know when you’re done. When you’re defining problems to be solved (and therefore solutions), you must also define the measures by which the solution will be judged.
A measurement of success for “Cost of Operation is Too High” might be “reduce costs of operation by 10%.” This gives you a testable criteria for knowing when that problem has been sufficiently solved. Sticking with the Ishikawa, you can also map out the strategy for achieving that lofty goal. You can say that the goal is to reduce fuel expenses by 20%, reduce cost of maintenance by 5%, and reduce payments by 15%. This process continues – a 20% reduction in fuel spend requires that you operate with your tires within 5% of nominal pressure, and that you reduce the aerodynamic drag coefficient by 7% (or whatever).
This gives you clarity in your objectives.
User stories, when combined with user acceptance criteria, provide that last connection of testability that lets your team know when they are done.
There aren’t many things more frustrating to a development team than having them solve the wrong problems. One of those things might be having their solution be rejected because it isn’t enough. Writing acceptance criteria clearly and concisely lets the team know exactly when they can move on to the next problem.
Providing a crisp understanding of acceptance criteria also facilitates iterative development. One challenge teams always face is making improvements that fit within the timebox of a given iteration. Imagine a user story with 4 acceptance criteria, where the story is too big to complete in one sprint. When talking with your development team, you may find that the story is too big because satisfying all of the acceptance criteria is too big. This is where many teams miss an opportunity – by defining all of the acceptance criteria that are believed to be needed eventually and requiring that they all be implemented now. One of those criteria is going to be more important than the others. Implement the story such that is satisfies the most important criteria (timeboxing) now, and rewrite or enhance it to meet the additional criteria later.
Conclusion
Software Product Success depends not only on identifying the “right stuff” to build, but on making sure the team builds it and builds it right.
Concise requirements improve your ability to communicate with your team, thereby improving their ability to build the right stuff right.
Latest Articles
Comments on all Articles
