Pragmatic Marketing has a training seminar called Requirements That Work. In support of that, they provide a list of 8 characteristics of good requirements. We change one and add two more to round it out to The Big Ten Rules. Combine this with Michael’s ten tips for writing MRDs, and we’ve got a good handle on how to create a great MRD.
Pragmatic’s List (1-8) + Two Three Four More
- Necessary Valuable
- Concise
- Design Free
- Attainable
- Complete
- Consistent
- Unambiguous
- Verifiable
- Atomic
- Passionate
- Correct
- Stylish
Looking at each rule of writing good requirements…
1. Valuable
Updated for 2009
Writing valuable requirements is important. It doesn’t matter how well your teams execute if they are off building the wrong products / capabilities / features. The right products and capabilities are the ones that have relevant value.
- Valuable requirements solve problems in your market.
- Valuable requirements support your business strategy.
- Valuable requirements solve problems for your users.
- Valuable requirements meet your buyers’ criteria.
- Valuable requirements don’t over-solve the problems.
Pragmatic uses necessary as a criteria of good requirements. We believe that valuable requirements are good requirements. When prioritizing requirements, we should do the must-have requirements first. But other valuable requirements are critically important – even if they aren’t mandatory. Prioritization and release scheduling should stress necessary requirements first, and then the most valuable requirements next.
Requirements that can differentiate our product from the competition are by definition not necessary – or the competition would have done it already.
[Update: Our detailed article on Writing Valuable Requirements ]
2. Concise
Updated for 2009
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.
Easy to read and understand. If only it were that easy. For whom is it easy to read? A market requirements document (MRD) is written for several different people on the team. It provides a vision of what problems our product solves. It provides clarification to the implementation team. It also sets expectations with stakeholders. Different people on the team have different domains of expertise – we have to write requirements that are easily understood by all of them.
[Update: Our detailed article on Writing Concise Requirements]
3. Design Free
Updated for 2009
Design-Free requirements are important for two reasons, and hard for two other reasons.
Design-free requirements are hard because you “know what you want†when you should be documenting “why you want it.†Writing design-free requirements can be hard when you don’t trust your development team to “do the right thing†even though it is not your job to design the solution.
Generally, a requirement should not specifiy any of the implementation choices. From a product manager’s perspective the requirement is the ‘what’ and the spec is the ‘how’. To a system designer or architect or lead developer, the requirement serves as a ‘why’.
[Update: Our detailed article on Writing Design-Free Requirements]
4. Attainable
Updated for 2009
Unless you live in a world filled with unicorns and rainbows, writing realistic requirements is critical. When you set unattainable goals, the best result you can hope for is a frustrated engineering team. Write requirements that are attainable, and your team will surprise you with what they can achieve.
The requirement must be realistically achievable. Barbara and Steve make great points about understanding the cost of implementing something as expressed in the requirements. As we pointed out in our thoughts about good requirements management, there is an optimal tradeoff between costs and benefits for any given company or project. We can formally approach this using the techniques identified for more is better requirements using a Kano framework. In short, the investment must have an ROI that exceeds the opportunity costs by the hurdle rate.
Looking at cost-benefit tradeoffs also supports the argument that valuable should replace necessary.
[Update: Our detailed article on Writing Attainable Requirements]
5. Complete
Updated for 2010
You give your requirements to the engineering team, and they look complete. The team builds your product, you launch it and the market soundly rejects it. Why? Because your requirements weren’t complete – they didn’t actually solve the problem that needed to be solved.
Simply put, if the requirement is implented as written, the market need is completely addressed. No additional requirements are required. When writing a specification, we may use decomposition to break individual requirements into more manageable, less abstract criteria.
[Update: Our detailed article on Writing Complete Requirements]
6. Consistent
Updated for 2010
Consistency in writing requirements is important on two levels – strategic and tactical. Tactically, you need to write your requirements with grammatical consistency, so that potentially ambiguous statements will be interpreted similarly. You also need to write requirements that are logically consistent, so that you avoid “impossible†requirements and gaps of unspecified meaning. Strategically, your requirements need to reflect a focus on markets and problems that are consistent with your business objectives and the vision your company is manifesting
Pragmatic Marketing highlights that the requirement must be logically consistent with the other requirements in the document – no overlaps, no contradictions, no duplications. This is certainly the most important point of consistency.
There is also benefit to consistent writing in an MRD. We can use templates to provide a consistent framework, but more importantly the prose needs to be consistent. This consistency makes it easier on the readers.
[Update: Our detailed aricle on Writing Consistent Requirements]
7. Unambiguous
Updated for 2010
Writing unambiguous requirements is about understanding what is written, and what is read. Without a clear understanding of your market, you can’t write unambiguously. Even when you understand your market, you risk writing something that is ambiguous to your readers. Documenting requirements is about communication. Don’t break this rule, or you’ve wasted all the energy you spent understanding your requirements.
A great requirement has a single interpretation. A good requirement has a single reasonable interpretation. As part of our development process, we will use listening skills like active listening to make sure that our engineering team understands the requirement we intended to write. The better the requirements, the less expensive and risky this communication process will be. Writing unambiguously is critically important when using outsourcing models that limit our interactions with other team members.
[Update: Our detailed article on Writing Unambiguous Requirements]
8. Verifiable
Updated for 2010
Writing Verifiable Requirements should be a rule that does not need to be written. Everyone reading this has seen or created requirements that can not be verified. The primary reason for writing requirements is to communicate to the team what they need to accomplish. If you can’t verify that what the team delivered is acceptable, neither can the team. This may be the most obvious of the rules of writing requirements – but it is ignored every day.
We use a process that starts with market requirements, and then decomposes them into software requirement specifications. the market requirements must be written in a way that we can verify that the associated requirements specification will meet the market need.
[Update: Our detailed article on Writing Verifiable Requirements]
9. Atomic
Updated for 2010
Each requirement you write represents a single market need, that you either satisfy or fail to satisfy. A well written requirement is independently deliverable and represents an incremental increase in the value of your software. That is the definition of an atomic requirement. Read on to see why atomic requirements are important.
Every requirement should be a single requirement. If we can say “Half of this requirement is implemented†then this needs to be two or more requirements. If a requirement read “Sales reps can manage their client list and generate custom reports†it expresses two atomic ideas (list management and report generation). Those ideas need to be separated
[Update: Our detailed article on Writing Atomic Requirements]
10. Passionate
Nothing great has been born from complacency, lethargy or mediocrity. When we are defining requirements, we must be passionate about what we’re doing. If we’re just going through the motions, it shows up in the writing. If we aren’t excited about a requirement, the problem is either with us or with the requirement. Either way, it won’t inspire the rest of the team to do something great.
[Update: Our detailed article on Writing Passionate Requirements]
11. Correct
[Update: Added 30 Oct 2006]
In addition to all of the analyses above, a requirement must actually further the objective it supports, and must be neccessary to meeting that objective, given a particular approach to solving the problem.
Our detailed article on Writing Correct Requirements.
12. Stylish
[Update: Added 5 Jan 2007]
Style can also be the difference between a well-crafted requirement and one that is hard to read. And style, applied consistently across requirements makes it easier to view them as a whole, and identify gaps and inconsistencies. This ease of comprehension matters when trying to achieve correct, consistent, complete requirements.
Our detailed article on Writing Stylish Requirements.
Summary
There isn’t really anything to summarize – this article is one big summary.
I would like to take a moment to thank everyone who has been subscribing, reading, commenting, and sharing Tyner Blain. We started this site six months ago and I am continually surprised, flattered, and thankful for all of the readers and support we have.
Thank you very much!
Scott
Let me propose another: Object-Oriented.
Here is a great essay by Edward V. Berard that does a much better job than my feeble attempt.
Thanks James! I’ve added a link to his collection of essays to the top of the page, I think other folks will really like it too!
Great overview!
I need to work through the detailed articles and reconcile with my own list of requirem1ent questions. This is a checklist I use to validate a requirement. I have a separate checklist for specifications in general, which covers the more general points like conciseness and unambiguousness.
At least we agree to put value at the top of the list! Do we agree to judge the merit of all the others using this criterion? To give one example: how much more value does a concise requirement add than a verbose one? My most concise requirements generally lack the immediacy of some of my more verbose ones. And requirements full of redundancy have an interesting characteristic, in my experience: they are less likely to be completely wrong!
Thanks Alan, both for reading and commenting!
The original list order comes from pragmatic marketing’s list of eight characteristics. That said, I think valuable is the most important – no reason to waste time on requirements without value. Correctness is the next most important characteristic – if we get it wrong, it doesn’t matter how well it is understood. I would follow that with unambiguous – even if we document the right stuff, and write it down accurately, it is worthless if our writing is misunderstood.
I would follow those with completeness and consistency, then attainable and verifiable. Then design-free, atomic, passionate, concise, and stylish.
I break it down into “stuff we must do to have a chance” and “stuff that makes us better / more efficient.”
How would you (or anyone else) prioritize these elements relative to one another?
Valuable first, of course!
Then, of similar importance: attainable, verifiable and complete.
Then: unambiguous and consistent.
Then: correct!!
Then: design freee and atomic.
Then: passionate and stylish
Finally: concise.
So… we agree about the most important and the least important, but we diverge interestingly in between.
I rank attainable more highly because it is closely linked to valuable: What use is a hugely valuable and otherwise “perfect” requirement if it is simply unattainable?
I rank correctness less highly because much of the value of correctness is delivered by the higher priority properties. The definition above says the requirement “must actually further the objective it supports”, for example. In my view, the proposition that the requirement is valuable ensures this. So it is valuable, attainable, verifiable, complete, unambiguous and consistent… but also incorrect… Can’t be very incorrect, it seems to me!
Thanks very much, Alan.
On attainable vs. valuable. A bit of a catch-22. It must be both. But I think it is easier to redefine a valuable requirement (perhaps eroding the value) until it is attainable, than it it is to redefine an attainable requirement until it is valuable.
Good point about correctness versus value. I think about it in terms of context. A valuable goal might have been for the USA to “beat” the Soviets in the geopolitical realm. Two requirements may have been “be first to the moon” and “devalue their ICBMs.” Those requirements embody some ideation – a strategy towards achieving the objective. Both have a ‘value’ and both have ‘correctness’ – but as you say, those notions are intertwined.
Really fun to think about it with this level of rigor, especially when revisiting (for me, anyway) these earlier articles. Thanks!
Hey all – I just updated with links to the latest articles revisiting writing complete requirements and writing consistent requirements.
As I continue to revisit the individual “rules” and update the references from this article, I will add comments here for those who are subscribed – making it easier to keep track of the updates, as they are spread out, often several weeks apart.
Thanks to all who are reading / following / tweeting!
Scott (@sehlhorst on Twitter)
Testable?
Hey mj, thanks for the comment and welcome to Tyner Blain!
That’s where I was going with “verifiable” – I used verify instead of test, since requirements “verification” is a pretty consistently used term with companies I’ve worked with. When I was a developer, I always thought of it as “testable”, but once I moved into requirements-authoring, I saw that people thought of it as “verifiable.”
“Testing”, I think, also carries a bit of a connotation of metrics versus measurement. As an example, you can absolutely “test” or “verify” that the system must respond in 20 ms. Either word works. But it feels more comfortable to “verify” that net-promoter score has risen, or that market share has increased. Yes, you can “test” that stuff – they are synonyms after all, but people outside of “write the code” land seem to gravitate towards verify.
Does that resonate? Or should I consider changing the title? If you read the article, it should be clear – but maybe a better title would be more effective?
Yes, yes…. I guess I was to quick. Verifiable is the right word to use… I am a tester and like to use the word “testable” to customers that is not very advance. I am trying to define for a customer how he should write the requirements and searching the Internet for stuff like this to send him, so I did not read everything word by word…
In my world you verify code but the requirements should be verifiable… You cannot verify requirements because you have nothing to compare it to? but do not listen to me, because this is just me philosophizes and I am very new in this world…
Thanks – makes sense! Hopefully this was helpful for you! From a tester-working-with-customers point of view, I’ve had success getting people to keep a few ideas as separate (but both important): (1) testing to make sure the code is doing what the developer intended, (2) testing to make sure the code is doing what the requirements-writer intended, (3) testing to make sure the code is doing what the customer intended (even if the requirements-writer missed it), (4) testing to make sure that the product is delivering value to the customers (think of Ford’s “faster horse” – customers don’t always ask for what they need, or need what they ask for), (5) testing to make sure that the product is succeeding in the market.
Each requires a different approach. Verifiable requirements really only tackle (2). Developers writing tests gets you (1). (3-5) come from getting the right requirements, not just getting the requirements (written) right (sic: correctly).
Thanks again,
Scott
I am sharing requirements management best practices with my peers in our recently formed business analyst Center of Excellent. I have given rave reviews and links to these colleagues for your Big Ten (12) rules plus your dont use shall post. This is essential reading even if we don’t always agree on very detail in your rules. “5 Stars. So important it has expanded to 12 rules!
REVIEW: This blog post is not just about bad versus good. It actually explains differences between good requirements and great requirements. Pick and choose topics you want to dive more deeply into, as each of the twelve rules is also covered more in-depth in a stand-alone article.”
Thanks, Glenn! I really appreciate it.
Hello Scott
Thanks for the write up. However, I have a personal view point. What you have highlighted looks fine when everything is in order and all the stake holders are at the same wavelength.
But in all practical purposes, the business does not what they want and requirements keep changing very often during the project. In such situations, what you have suggested, many times does not hold good. I can actually go one by one on your view point and highlight why it is not that easy to achieve. Sorry if I am being pessimistic. But am seeking answers as to how to overcome in such situations. We, as business analysts are helpless as we are stuck between the business and the project / program manager.
Hey Vinod,
Really excellent point. Let me rephrase, so that I am certain we are talking about the same thing:
When the business changes its goals, and therefore its requirements, it doesn’t matter how effectively we communicate the no-longer-relevant requirements.
I completely agree. I think there are multiple opportunities for “failure” in the chain, and writing effectively does not address the issue of having a moving target. However, I would point out that even once you do reach agreement about what the goals – and therefore requirements – are, if you cannot communicate them effectively, it does not matter that you “know” them. This series of posts is really only focusing on being effective at eliciting (e.g. “correct and complete”) and communicating (e.g. “concise and atomic”) the requirements.
In trying to make forward progress, I did my best to not conflate the different problem spaces (although correctness is both an eliciting and communicating aspect).
From my personal experience, I have seen that while businesses do change objectives, nine times out of ten, what is really happening is that the requirements were not clearly discovered, articulated, clarified and documented. What looks like “changing requirements from the business” is actually “changing documentation, as we get closer to capturing an understanding of the unchanging requirements.” That’s really where this series is aimed.
Please let me know if that’s consistent with what you’re seeing, or maybe I’m missing the mark with your concerns entirely – please let me know.
Also, thanks for joining in the discussion and welcome to Tyner Blain!
The concept you’re discussing with Vinod is requirements stability. Individual requirements must be stable in that the value to which they are to be verified must be specified and not change. Beyond that, at some point, the customer, engineering staff, or any other stakeholder responsible for determining requirements must know when to stop adding to the set of requirements, regardless of how well they are written. More programs have blown through their budget and/or schedule; or have just been killed off due to requirements churn than for any other reason.
Hi Scott,
Thanks for a good summary of what it take to write good requirements.
I would like to add that it is also very important to include meta data for requirements such as priority, responsible stakeholder etc. to make the subsequent management of the requirements effective.
I have written about this previously if I might add that to the above discussion here:
Top 10 writing good requirements tips
Thanks again for a good summary and discussion!