How to Write A Good Software Requirement

requirementsfishboneSoftware development lifecycle processes can sometimes be seen as impediments or tedious tasks. But it is worth reminding everyone that the smart work up front will save you headaches later. In my experience, well-written software requirements serve two main purposes: it orients all project participants and helps get buy-in about what you’re trying to do (since you’re articulating what you’re trying to accomplish), and it makes sure that everyone (from the project sponsor(s) down to the technologist and back up to the end user) can say that the project is done to expectations.

The trick is how to write a good requirement, for any number of situations. Part of the answer is to follow this convention:

The [your words here: system, actor, function, dependency, etc.]
must [your words here: do, process, store, etc.]
to [your words here: accomplish a goal, serve a purpose, etc.].

and to focus on the “what” (substance) of the need as opposed to the “how” (design) of the need. In addition, there are 8 key criteria that each requirement should satisfy to be considered well written.

As a business analyst, you should think about addressing the following points to evaluate how well written the requirement is:

  • Necessity €“ A “must have”. Conversely, it helps to avoid gold-plating and gives you a prioritization tool during the build phase of work.
  • Unambiguous-ness €“ Use assertive words without vague terms. This also helps the writer/stakeholder focus on the “what” of the product/service/result as opposed to the “how” and proactively reducing interpretation issues.
  • Testability €“ Can be verified by inspection, analysis, or demonstration, which means that there’s a qualifying attribute to almost everything based on the idea that you know it when you see it.
  • Conciseness €“ Conveys what is required and is easy to read yet. If you end up writing a page-long requirement, it’s time to make it more atomic.
  • Consistency €“ Does not contradict other requirements and uses a known vocabulary that should be defined for the layman (or at least the wider group).
  • Completeness €“ Does not require you to look at additional text to know what the requirement means. At the same time, requirements may be related to each other, which then requires the writer to add a separate requirement that talks about interaction between multiple requirements.
  • Feasibility €“ A requirement that can be implemented. Typically, time is a factor, but cost and available resources will all ultimately play a role in what you deem feasible or realistic.
  • Traceability €“ Has a unique identifier and is tracked through the development of the product/service/result. Along with testability, this attribute plays a role in ensuring that things do not get lost in the cracks.

The above list was adapted from here based on my own experience, and there is a wealth of material on the Web and in print that follows these conventions (or their spirit). Unfortunately, despite the volumes dedicated to this topic, it still frustrates users and is a task that is taken lightly because it is time spent with seemingly less tangible benefit up front. I have had many experiences where the team will ask “What did (insert name) mean when he/she wrote this,” which resulted in time wasted, potentially incorrect coding to occur, and costly testing time and effort down the line that reveals something “wrong” with the system but is hard to define or pin down.

Recommendation: Do the work upfront, and you’ll save time and headache later. As a business stakeholder, focus on the “what”, and allow technical subject matter experts worry about the “how” (which they are supposed to do anyway). Well-written requirements based on necessity, unambiguousness, testability, conciseness, consistency, completeness, feasibility, and traceability will save the day.

Comments are closed.