Blog

How to Write Good Requirements

performance improvement quality improvement

NOT like this!

Why should business people care quality improvements through better requirements for products or services?  Because what we build is only as good as why we built it.  We often express our “why” in the form of requirements.  Yet… after many years, product and service developers still don’t do a very good job or writing requirements.  Here’s what to look for in a requirements set, and what feedback to give the requirements writers.

We’ve handled lots of new product or service requirements.  Most requirements sets were too long and too complicated.  The language of the individual requirements was too general; or overly restrictive without being specific.  Many requirements sets had seemingly duplicative requirements, but the subtle differences wereassumed away or left unwritten.  The clear, concise language of the first draft was edited away through multiple review cycles.  How could this happen?  Because of all the this is a surefire way to short circuit product quality improvement.

It seems that everyone knows about requirements.  But it also seems that few people realize that writing good requirements is a skill that needs to be practiced.  Unfortunately, most requirements writers do their practicing as they actually write requirements.  When pressed, they explain that they know how to write requirements… but don’t actually say their skills are up to to the work.

The customer: “This is my system, I should certainly know how to describe what I need.”

The project manager: “I’m  building this system, I know what needs to be described… and how to describe it”.

The software engineer: “I’m the  designer, tell me the functionality and I’ll get on with the job.”

The coder(s): “Who wrote these?  They don’t make any sense.”

The customer representative, during acceptance testing: “This isn’t what we need.  This can’t be what we asked for…”

Another project late and over budget, because not one of these know-it-alls actually knew how to express needs simply, clearly and knowledgeably.

There’s lots of advice available on how to develop requirements.  Most of it involves doing more; we say, do less, carefully.  Today we’ll give you our advice in a short and sweet summary form:

  • develop as few requirements as possible
  • express those few requirements as clearly as possible
  • take steps to minimize the unintended consequences of your requirements
  • make it possible to revise the requirements set

That’s how we use requirements to drive product performance improvement and quality improvement.

Few Requirements…

The fewest number of requirements is zero. It turns out there’s a case for skipping requirements when:

  • you’re building/modifying as system as part of Kaizen (continuous improvement) campaign
  • when your small organization can say “we need what we have… except for…”
  • you have a real domain expert who says “I’ll know it when I see it”, then prototype immediately

Alright, your project doesn’t meet any of the above qualifications.   We need to develop a set of requirements.  Still, you can minimize requirements by:

  • re-using existing requirements… purposefully.   Always, always, always reread and edit ruthlessly
  • citing the relevant part of a standard, protocol or best practice; don’t just reference the entire document
  • not duplicating requirements within your requirements set; reference the repetitive need.

… Clearly Expressed…

We express requirements most clearly by:

  • using short, simple, declarative statements in the active voice (imitate Hemingway, not Faulkner)
  • using specific numeric values and enumerated lists; “not less than” and “including” are bad requirements language
  • breaking up requirements sets into functional, performance, infrastructure and interface subgroups… but no more
  • specifying a user interface using diagrams or a simulation
  • specifying a calculation using a formula and citing the source, or providing a spreadsheet or Matlab script
  • using pseudocode when technical users (not developers) feel comfortable with it.

[Here’s a hint.  If you find yourself staring uneasily at a text requirement with two sentences, five clauses, and phrases  like “including but not limited to…”, call your former English teacher.  Ask for a refresher in sentence diagramming.  We’re often surprised and dismayed at the plain meaning uncovered by the sentence-diagrammed requirement; it’s not what anyone intended. ]

… Without Unintended Consequences…

Unintended consequences can be unbelievably costly and time-consuming.  We can proactively minimize unintended consequences by:

  • building an accompanying glossary to minimize misunderstandings
  • not (repeat, NOT) adding “amplifications” or “comments” to requirements
  • knowing the domain’s science and/or the state of the technical art; don’t force leading/bleeding edge performance by default or accident
  • recognizing that good requirements are inspectable/testable; it’s often cheaper to build the test plan in parallel with the requirements description.  (When I couldn’t, there was usually a problem with the requirements.)
  • not creating a requirements spreadsheet; spreadsheets are the most common and ultimately costly requirements documentation format.  Use a requirements development application.

… And Written to be Revised.

Let’s build requirements to allow for change.  The cited standards may be updated.  The edge of technology (and occasionally, the boundaries of known science) may expand. The underlying business case or mission will probably evolve. And we’re all imperfect requirements developers… right?  We can allow for change by:

  • being unafraid to rewrite a requirement or add to an enumerated list
  • being unafraid to change a diagram, formula, or pseudocode, but always explicitly highlighting the change
  • being wary of adding new requirements, or complicating the structure and vocabulary of an existing requirement
  • being open to the idea that the best change might involve using that handy “delete” key

(You’ve probably guessed this already… developing great requirements depends on attitude as well as specific technique.)

Here’s a tip.  If you can write great requirements, why not also try imagineering?  The combining these two business innovations might just be your path towards a small business success story.

Lastly, requirements sometimes have long gestation periods because someone needs time to build support for funding the development.  In this case, do yourself a favor.   Offer that someone (project sponsor, product manager, etc.)  another less costly activity to consume time while building support.  Why?  Good requirements descriptions, perversely, deteriorate as multiple revision cycles take their toll.    The result almost always leaches time and money from the project budget. Not to mention draining performance and quality.  Your high performance implementation teams deserve great requirements; your customers deserve the product performance and quality improvement.  Don’t they?

Tags

 

7 Comments

  1. Fantastic article! ! Requirements analysis is of vital importance in the whole project implementation. Good requirements can lead the benign development of the project, it will also save time and money from the project budget. The suggested method are worth learning, I will share it with my company’s requirements analyst.

  2. Great view on how diffrent people with diffrent career and character precive the same requirements in their own way. We should always be sure that everyone can give their input on how they see the requirements. Often in our office are requirements not understood correctly, so they can not be efficent.

  3. Carol Orris says:

    I greatly appreciate this article. Often times I have an end goal in mind, just lack the knowledge to execute it. Thank you for making practical, concise information available to us all.

  4. That’s wonderful Chris. I’m sure it will clarify even more how we should reason our requirements.

  5. CRISTOVAM PERES says:

    This article is very applicable when creating the Product Backlog for a Scrum project. It always should be simple, concise, pragmatic and testable. Here in Brazil we’re now living the beginning of the transition from old waterfall model to agile project developing for all areas of businesses. This is a must read for all involved in these activities.
    Do you have any good vs bad requirements comparison?

    • Chris Chadbourne says:

      Since you asked… I’ve got some good ones in the archives… I’ll see what I can package and publish.

  6. James Ojuok says:

    Very informative indeed..I now know the significance of good reqyuirements, and that it is actually a skill!

Leave a Reply

Your email address will not be published. Required fields are marked *

*