Defining Great Requirements

 This is a link

Managing software development is a hard ballancing act where one approach does not suite all. Here, we willl look at how you manage the requirements engineering phase of any project wheather your using interations, Agile, or whether you have outsourced your development or are developing in-house.

Whichever appraoch you have taken the most important thing to remember is to take an engineering approach. This includes the ininital definition of the software, including the business case, prior to developing the software itself.

If your project is developed in-house (the best way), then you can take a Agile approach. This will give you software which is sufficent for the job for the best possible price.

If you have outsourced your software, or need to define all your requirements up-front,  then you need to define your acceptance criteria before you start buring significant resources on development costs.

So before we get into the two different approaches of when we defined the requirements lets first say something about how we record them.

Product Backlog

Requirements should alway be recored in a product backlog which is nothing more than collection of requirements specified as stories or use-cases or goals of the system. Sounds a bit wishy-washy? Well you would be right.

The requireents in the Product Backlog should not be so vague (single sentance), that you don't understand what the implications of these requirements are nor that you can't anticipate the nuances of their impact on the overall system. No-one can build a great system from the requirement "Creat Address Lookup Module". What the hell does that mean? But more on this latter.

Equally, you don't want to spend so much time thinking about the requirements that you over emphasie and over antcipate what the end product will be exactly like. This just leads to lots of guess work, costs, and you tie yourself into a corner that latter on you find a bit unconfitable.

So a great requiement is at the right level. So write down what you know at the time you know it, and don't spend too much time predicting the future. Basically, make sure the requirement can be read within about 3 minutes - about 1/2 a page Arial at font size 10. Use a diagram or picture if it helps convay meaning.

Developing Requiremets - Defining a Story

I'm going to stick with the idea of defining requirments by using Stories because it is a pritty effective way for requirements definition. Using Functional Requirements list is not. If you want to use list of functional requirements then please don't insult this web site any more and please move on.

So how do you define a story? In the begining days of Object-Oriented Analsys and Design, we used to define use cases (stories) as having a Main Flow (which was the most common usage), and then Alternative Flows (which were things such as when errors happened, or event occured that diviated from the Main Flow). The problem with this approach was that it was very documentation intensive and pritty much boring as hell. Here is an example of a Main Flow for entring an address:

  1. The user will enter their postcode.
  2. The system will validate the postcode and display a list of matching addresses.
  3. The user will select the address that matches where they live.
  4. The system will record the address.

Naturally, from this there can be lots of Alternative Flows, the postcode not being valid, not finding any maching addresses, the user's address not being in the list, the user selecting the wrong address, and so on and on. The good side of this is that it did make you think about the system in some detail. However, its boring to read and boring to write, and when you've got tonns of documents that describe all these little steps in the system all you want to do is have a labotomy and become a project manager.

But the good news is, if you're a Supplyer company and you've managed to get your customer to agree to be responsible for defineing the requirements and not working in a agile way, then you'll have no problem finding holes in loads of these Use Case documents and hitting the customer with lots of Change Requests - ching ching.

Describing a Story

So the best way to describe a story is not to think about it too hard (afterall Developers wages have been going down for the last few years, so our workload should be going down too), and to define them in a way that is accreate but not too clunky.

So for example, how about:

The user will enter their address using a postcode lookup system. The system must be able to cope with invalid postcodes, no found matches,  the user selecting the wrong address, and none of the returned addresses being anywhere where the user lives.

Hows that? Isn't that enough for anyone to develop from and any stakeholder to understand what is meant.

In reallty, your stories in a much larger than this, but the essence is to keep it simple, understanable and not to confusing. Also make sure it can be demonstrated. If you want, you may even specify what you would like to see demonstrated - there may be a particular part of the system that is particullary important. So you'll want to see it in the demo.

So this brings us to another key point:

  • The purpose of a story is that it is demonstrable once it is developed.

If your story is about a user interaction with the system then this is easy enough, but if it is a techical story about some interaction with an external system then you may have to demonstrate this via a test harness and log statements. Either way, each story has to be demonstrable.

So now we have an understanding of that how to create a Product Backlog lets look what happends if you have to define all your requirements up front.

Defining All Requirements First

The point of defining all requirements up front is that it gives you a fixed baseline from which to start development. This means that costs can be predictable and thus it's a technique suited to outsourcing or fixed price contracts. It is very difficult to price a system when you don't know what it will be.

However, if you want to define all your requirements up-front then you have to do so by starting from where you want to end-up rather than starting from where you are at the start.

  • Start from the finish line, not the starting line

The downside is that you will only get about 65% 80% return on your investment (ROI). This is because the Devil is in the detail and the product you specify up front will not be what you want when it gets developed. Consiquently you will have change requests to deal with, and each one of those change requests was time waisted in the orgianal requirements engineering phase, and also has the added overhead of administering the change request system.

BTW. If you are outsourcing development to large companies, it is via the Change Request mechanism that they make most of their money. Many of the large projects I have worked on, particullary goverment projects, the client gets screwed because the supplier purposfully defines loose or slack requirements knowing that they will need to be clarified or frimed-up latter. And that, my friends, is an opertunity for a Change Request.

  • Define Stories through Prototypes, Screenshots, and Mockups

The most important thing about defining requirements up front is not to document them - prototype them. So develop working screen mockups of your entire system, or at least as much as you can. Don't bother writting any documents because if you're going to define all your requiremnts up-front then no-one will read them, and certainly not good engeneers. Good software is visible and therefor should be expressed visually. And eveyone knowns detailed text based requirements are not worth the diskspace they're stored on.

When Not to Define All Your Requirements Up-Front

There are some circumstances where even if you're outsourcing and you want to define all those requiremnets up front, you shouldn't. This when the project is very large and will be going on for some years.

  • Do not define All requirements for very large projects

If your project is larger or will be ongoing for years then it would be a big mistake to defined all your requirements upfront and you'll need to defined them sub-system by sub-system. This will also make sure that you supplier can deilver.

Sure, you will still need a good understanding of at least the general direction you want you software to go in. But even this should be flexible. There are plenty of examples of software designed for one thing (search), and then ended up being usedfor something else (selling addvertising). So don't think that today you know what you software will be used for and look like in 3 years time.

The longer out your project is going to run for the more flexibility you have to build into your development plan. Fortunetly, this isn't too dificult as all it means is we take one step at a time and look to the near future whilest keeping an eye on the far future.

Protypes and Mockups

Prototype or mockup everything.

If you have interfaces to third party systems then you define your side of the interface, and let the third party provide the translation layer between what you want and what they provide. If this is not possible because they simply would not do it, then you should still defined the interface that you want and then write the integration code to make it work.

Desiging you requirements visually also enables you to test your assumptions around the scope, workflow and usability of those requirements. It also enables developers to write Selinimum tests which can run against the prototype which should also run against the finished product. Thus proving you've got what you asked for.

Here are the rules for a good requirements prototype/mockup.

  1. It does not have to be fully functional, but more functional the better.
  2. It should not be styled. Styling can be added latter - don't waist your time doing something that will hopefully change as the understanding of needs change.
  3. It should be quick and easy to develop. Don't get bogged down in details about what font should go where etc.
  4. The focus should be on general layout, placement of text and widgets, and thats about it.
  5. Do it in a browser, not in Word/Photoshop/Visio etc. I've seen projects where the screen mocks were presented in Word documents, and when the screens were developed for the computer screen they look real bad. Why? Because word presents documents in portrate, while most screens are in landscape.

Point 2 above hints at a very important aspect of developing a prototype during requiriements engineering. The prototype is not there to proove the requirements (at least in the early and middle phases), it's there to uncover and deeper understand requirements. So you should look to your prototype as a tool of change not as an end in itself. The more you're protoype changes the better you discovery of requirements. If you find that that your prototype is not changing very much then that is not a signe that you are on the way to having developed the most perfect of perfect products, but that you are not communicating good enought.

Sure, sooner or latter you're going to have to stop delving deeper and deeper into the nuannces of requiremnts, but thats when you've had enough and decided that the prototype is good enough to get the job done and act as a goal post for knowing when development is complete.

Incremental Requirements Definition

  • This is the most efficent and effect way for defining requirements - upto 95% ROI.

The Agile way for specifying requirements is to generally use a spreadsheet. This is fine, but does not reflect the way requirements need to be firmed up as you get closer to writing code against them.

For defining requirements the Agile way the best thing to do is to define them using as much knowledge as you have to hand at the time that you are defining them. This was outlined above when I was talking about Product backlogs.

Initially the purpose is to define as much scope as you can. So requirements do not have to be detailed, but they do have to be understandable. Again, see above.

So create your Product Backlog and some requirements may be single liners, and some will be a page of detail. Just write down what you know, and don't write down what you don't. Unless, of course, you know what it is that you don't know (encrption needed for personal data, but not decided how).


This is step 1 about how to create great software. Fistly you need to think you know what your goals and where you are going. Great software does not come form single line statements in spreadsheets. Great software does not come from details specs. And great software has never come from functional specs.

Great software comes from a starting possition of knowing the best you know at the time, but understanding that as development moves forward requirements may change and you will have to follow.

Greate software, like great Aikido, come from the streath of great flexibility.

Add comment