Quick Tip: Writing Requirement Statements

Structure

The ‘As a <user type>, I want to <action to be performed>, so that <business benefit>‘ user story structure encourages good requirements but can often be abused!

If you’re tasked with writing user stories or requirements, then I suggest that you read the Open Unified Process documentation guidance on ‘Writing good requirements‘:

• Define one requirement at a time.
• Avoid conjunctions (and, or) that make multiple requirements.
• Avoid let-out clauses or words that imply options or exceptions (unless, except, if necessary, but).
• Use simple, direct sentences.
• Use a limited (500-word) vocabulary, especially if your audience is international.
• Identify the type of user who needs each requirement.
• Focus on stating what result you will provide for that type of user.
• Define verifiable criteria.

(see the OpenUP wiki link for the introduction and examples)

Numbering

Or rather: numbering schemes with respect to grouping and ordering

For traceability it is critical for a requirement to have a unique identifier. No arguments on that front, but the challenge comes when people get to choose their own numbering scheme for requirements.

e.g.

1. First requirement
2. Second requirement
3. Third requirement

All good so far you might think – it’s exactly the way they be numbered if I’d entered them in an issue tracker.
Well let’s suppose that at the first pass that the list is in a spreadsheet, was collated by functional area and contains over 50 items.

It can easily go awry on subsequent iterations (e.g. after review cycles, prioritisation meetings etc.) when people haven’t written good requirements (see above) or you have epics that need splitting. At this point a system would append a row which is given a sequentially generated primary key, whereas with a spreadsheet the natural inclination is to insert a row into the table which then introduces the numbering dilemma.

There are 3 common behaviours:

• Generations of people trained in using numbered headings in documents will typically go with the nesting instinct e.g. 2.1.3
• Information workers who’ve dealt with numbering schemes such as Dewey Decimal might have used non-contiguous numbering in the first place e.g. start each new functional area at the next 100 – which may prevent or just defer the issue
• Data modellers may opt for the foreign key approach for splits and use other columns for grouping/sorting.

I’d encourage the latter approach, append to the table then re-sort later and don’t get hung up on having beautifully ordered reference numbers. After all you’re not doing Big Requirements Up Front are you?

Final thought

“Adding power makes you faster on the straights. Subtracting weight makes you faster everywhere” – Colin Chapman

Think about the implications of this philosophy when writing and prioritising requirements!