My eyes, my eyes, the goggles, they do nothing!

13 May, 2015 by Jason Clements

On the day before build started, God (substitute ‘the mice’, if you prefer Douglas Adams’ version) realised he didn't know what he needed to do. So on Day 0, God created a BA and the BA wrote up his requirements and God build the world in an iterative manner (6 sprints, go-live at the end of the last sprint - little bit big bang, but no-one’s perfect). There were a couple of changes (one major one involving a release of World 2.0 following a flood that the DR system couldn't handle) but in terms of fixed price, fixed scope projects it came in pretty much on time.

Then fast forward a few millennia and a specification of how to write requirements (IEEE 830 Recommended Practice for Software Requirements Specifications) was written. IEEE 830 was created in 1984, revised in 1998 and superseded by IEEE 29148 in 2011.

For those of you who don't want to read IEEE specifications (and I don't blame you for that), the format of a requirement goes like this:

The system SHALL allow the user to input expenses

The system SHALL total the expenses

The system SHALL get billing data from a third party

The system SHALL have a calendar to look up dates

The system SHALL let the user review the expenses

The system SHALL let the user approve the expenses

The system SHALL let the user submit the expenses

The system SHALL send an alert to approvers when an expense has been submitted


The keyword (SHALL) can also be SHOULD, MUST, etc (it's in the specification, read it if you want).  Often these requirements are MoSCoW prioritised in tandem with the keyword - which means pretty much all of them will be put down as MUST HAVES without comprehending what MUST HAVE actually means.  For those who don't remember, MUST HAVE means that if it isn't there, the system will not work.  I.e the system is useless.  Worst case scenario is when the MoSCoW prioritisation and the keyword are in disagreement.  Which is the one that needs to treated as the actual priority?

The first problem with IEEE 830 requirements is they are BORING to read and write, prone to errors and duplication, wordy and lack a clear-cut owner.  With a system of reasonable complexity, you've probably got a spreadsheet with 4-500 of these bland statements on them, which simply don't work in an agile project.  This means the BA team spend hours unpicking, rephrasing, rewriting and mapping these requirements into something more intuitive and understandable. 

Second, when IEEE 830 was drafted, the concept of user centred development (or agile software development) didn't exist.  The Agile Manifesto wasn't written until 2001 and in 1984 the entire user experience was based around a green screen monitor and keyboard.  In that utopia (the one where the users didn't matter as most of them had never used a computer before, so expectations were low) and the mouse was a virtual unknown (aside, perhaps for the ones that had made a nest inside your Wang mainframe). Yes, I said mainframe and Wang in the same sentence, stop sniggering.

Third, it puts forward the idea that if everything that is on this checklist is built, life will be golden.  The problem is those pesky users.  Once they start to see working software, their initial thinking will evolve and change.  The use of the IEEE 830 requirements locks people down into a mindset of scope, scope management, change management, etc when we should be doing the exact opposite and welcoming change.

Fourth, it is hard to read these requirements without thinking of a solution as you do it.  For example;

The system SHALL have a screen

The system SHALL be hand hold able

The system SHALL store data entered

The system SHALL have a keyboard

The system SHALL be able to be used without connection to a power supply


You're probably thinking of an iPad at this point in time.  Maybe something shiny with nice new tech.  But what happens if we look at this by expressing it as a user story (using the INVEST principles) instead. 

As a warehouse picker I can check a barcode so that I know I have selected the right item

For starters, is this a well-written user story - does this meet the INVEST principles?

Independent - yes, this could be built by itself as a discrete piece of work

Negotiable - yes, we haven't locked it down as to how this can be achieved

Valuable - yes, by doing this the business will cut down on time wasted bringing back the wrong items

Estimable - yes, a developer could make an estimate as to how much effort would be needed to build this

Small - yes, it is not large or complex (and if it was, we would then break it down until it wasn't)

Testable - yes, we could test to see if a barcode on an item matches the item in front of us


So what does this user story tell us?


Straight away we know who the user is, what they want to do and why they want to do it.  We haven't committed ourselves to a piece of technology, nor have we carried out extensive analysis to figure out what is actually needed.  At this point, the idea of using an iPad is probably wrong, but if we stuck with the preconception derived from the IEEE 830 requirements, that is what we would likely go for.

It tells us that the warehouse pickers want to be able to make sure the widget they are grabbing off the shelf is the one they are supposed to be grabbing.  That's their goal.

What haven't we done?

We've not done a whole pile of analysis (or taken a wild guess) as to what the solution needs to look like.  We have stated what the user wants to do and why, what we haven't (and shouldn't at this point) done is specify how they are going to accomplish this.


So, do we have all the detail we need to implement this at this point in time?


Well, no, we don't.  A user story (or set of user stories) is not a requirement.  It is an expression of what the user wants to accomplish - i.e it is a goal.

It does not have enough information in it to tell a developer what needs to be built.  That's the purpose of acceptance criteria. 

It also doesn't tell the developer what it's going to look like (UX and creative designs as appropriate), nor does it give any constraints (i.e NFR's).  But we don't need to know any of these until we are about to build it, so we don't waste time figuring out now what or how the user can achieve their goal (selecting the right item).

It doesn't tell the developers what their approach needs to be.  Now, we may have an idea of the technical stack it is going to sit on, but we are not specifying that it needs to be done via a scanner, or typed in by the user, or recorded via the camera onto an app on a device.  And it doesn't need to.


To summarise

1. Please don't use the IEEE 830 style to write requirements – they will make someone’s eyes bleed.

2. Remember, friends don't let friends use the IEEE 830 style to write requirements.

3. Do write good user stories using the INVEST principles as a basis.

4. Treat user stories as goals, not requirements.