Writing Technical Requirements: The Third Commandment

Scot Witt, Tuesday, July 17, 2007 @ 10:45 am

Use Cases, User Stories, Functional Specification, Functional Decomposition, ad nauseum

These are all requirements developers, managers, QA and Technical Writers use at various points in the software development life cycle. Whatever you're writing, for whatever purpose, you need to keep it clear, it needs to be concise and it needs to be understandable to more than one audience.

This blog is a show by a couple of examples and comments rather than pithy items you can use immediately.

Here we go with the third Technical Requirements Writing Commandment:

III. Care for Use Cases and Make Them Fruitful to
Multiply

Let's use Use Cases as the example- they can be used in Waterfall and disciplined Agile. You write them like an in-depth User Story and Functional Specifications often include the really high level Use Cases.

Here's an okay example from Alastair Cockburn:

Scope: ATM
Level: User Goal
1. The card gets inserted.
2. The card information gets validated
3. The transaction information gets collected and validated
4. The cash is issued, card returned, cash removed, account debited and screen reset.

The Good:

• Simple wording
• Only four steps
• other than 'validated,' most people will understand this
• Nicely organized with nice grouping to reduce the number of steps.

So what are Scot's beefs with this one?

• I have no Use Case Title, Number or Context.
• The Actor (person or system performing the action) is never identified.
• There's no goal- you can infer it in Step #4, but I need to  know that before I start and so does my developer.
• I like step-action tables- the left column tells me what the actor's done and the right column tells me what happens.  That way, we all know what's happening.
• There's no error handling.
• Passive Voice (ugh!)- tell me who's performing the action, please!

An okay Example, but improvable.

Here's a really bad one from Cockburn:

(Withdraw Cash) (WEUC)

1. Customer runs ATM card through card reader
2. ATM reads the bank ID and account Number
3. ATM Asks customer whether to proceed in English or Spanish
4. Customer selects language
5. ATM asks for PIN Number and to press ENTER
6. Customer enters PON number and presses ENTER
7. AT presents a list of activities for the Customer to perform
8. Customer selects "withdraw cash"
9. ATM asks customer to say how much to withdraw, in multiples of $5 and to press Enter
   (it just continues like this)

The Good:

• There's a title.
• I can infer the goal from the title- the bad is I shouldn't have to infer anything).
• I assume WEUC has something to do with the numbering or classification system. More than what I had above, but not really good yet.

The Bad:

• I fell asleep at step 5.
• When was the last time an ATM actually talked to you?
• Am I the only person who understands PIN Number= Personal Identification Number Number?
• Where does the Customer do all these selecting acts?
• What exactly is this really cool list of 'activities?'

Our second example raise more questions than it answers. If I were the BA in a traditional shop, I would expect to be answering questions for a week on this. If I were working on an Agile Team, I'd split this into several User Stories for Customer review.

This use case also demands a long series of business rules.

While writing use cases, specifications and the like, consider organizing them, numbering systems and the like. Your readers need to be able to find stuff quickly and your PM needs to track your progress.

In future blogs, I have some thoughts on wikifying the process.

Stay tuned.

Next Up: Commandment IV. Business Rules Made Simple.

Related posts:

1. Writing Technical Requirements: The Second Commandment
2. Writing Technical Requirements: The First Commandment
3. Writing Technical Requirements: The Fifth Commandment
4. The Ten Commandments for Technical Requirements: VII: Presentation: The Art of Gladness
5. Writing Agile Requirements

Comments (2)

Technologies and Platforms

Comments: 2 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. 

   Scot,

   Love the idea of the 10 Commandments! And you’re also very funny!

   - Adrian
   http://www.ModernAnalyst.com

   Comment by analysis_manager, Saturday, September 1, 2007 @ 5:14 pm

2. 

   Hi Adrian!

   High praise indeed.

   Humor?

   

   Comment by Scot Witt, Monday, September 3, 2007 @ 11:01 am

Leave a comment