Posts Tagged ‘agile requirements’

A Requirements Challenge

Friday, January 23rd, 2009

I have always done highly iterative development and have always worked in short iterations. Initially this was because the domains I worked in early in my career gave me no choice but to work that way. Later I discovered the philosophical reasons for working this way. I also soon learned that keeping the software close to bug free was best. This was all back in the 1980s and early 1990s. In 1992 I started Mountain Goat Software to do outsourced, contract development projects and needed a name for the new company. I found the name in Tom Gilb’s wonderful Principles of Software Engineering book. Every page or two has a gray sidebar highlight some key principle. On page 99 is the Mountain Goat Principle:

Take one step at a time up the slippery mountainside, and make absolutely sure that each hoof is on solid ground before you take the next step.

I’ve always considered Tom to have been the original agilist. In 1989, he wrote about short iterations (each should be no more than 2% of the total project schedule). This was long before the rest of us had it figured out.
Although I’d named the company after one of Tom’s principles, I had never met him in person. Well, last month I finally had the honor of meeting Tom and his son, Kai Gilb, who is a top-notch software consultant in his own right. (See Kai’s book on the Evo process.

At dinner, Tom and Kai posed a challenge to me that I haven’t been able to figure out yet. We talked about how adding a new feature to a product is not an issue of adding new capabilities as much as it is about changing how well something can be done. I other words, it is about changing the quality of the implementation.

For example, imagine a simple word processor back in 1982 without an integrated spell-checker. Spell checking was still possible. You could have looked up each word on the screen in a physical dictionary and determined which were misspelled. Adding the integrated spell-checker was more about improving the quality of an implementation than about adding a new capability.

The challenge that Tom and Kai posed me was to think of a function in MS Word (any word processor will do), that is a new function, and not just a change in the quality of those functions. To think about this, compare Word of today with the tools of a century ago—paper, pen or pencil, the post office, and so on.

Surely, they were nuts, I thought. So I tossed off a few answers:

“Undo.”

“No,” they replied. “That could have been done in the old days with an eraser.”

“Printing.”

“No,” they replied. “That could be done by monks in a monastery making copies by hand.”

I tried a few more but came up empty. So, how about it? Can you help me by coming up with a feature in a word processor, like Microsoft Word, that is new functionality and not just a change in how well something could have been done with pencil, paper, and similar tools.

Posted in Musings | 37 Comments »

Non-functional Requirements as User Stories

Friday, November 21st, 2008

A common challenge with writing user stories is how to handle a product’s non-functional requirements. These are requirements that are not about specific functionality (“As a user of a word processor, I want to insert a table into my document.”), but are rather about an attribute or characteristic of the system. Examples include reliability, availability, portability, scalability, usability, maintainability. As you can see from that list, non-functional requirements are often referred to as “-ilities”. Of course, not all non-functional requirements end in “-ility.” We also have security, performance, robustness and so on.

Thinking back into the dark ages, I can remember when I first read about “non-functional requirements.” The term threw me for a loop. “If it’s non-functional, why do I care about it?” I’m sure the author of that book clarified this for me a page later, but the term has always seemed an odd one to me. I prefer to think of non-functional requirements as “constraints” we put on the system. When a product owner says “this system must perform adequately with 100,000 concurrent users” the product owner is putting a constraint on the development team. The product owner is effectively saying, “Develop this software any way you’d like as long as you achieve 100,000 concurrent users.” Each constraint we put on a system narrows the design choices a bit; calling these “constraints” rather than “non-functional requirements” helps us remember this.

Fortunately constraints / non-functional requirements can be easily handled as user stories. Here are a couple of examples:

  • As a customer, I want to be able to run your product on all versions of Windows from Windows 95 on.
  • As the CTO, I want the system to use our existing orders database rather than create a new one sot that we don’t have one more database to maintain.
  • As a user, I want the site to be available 99.999% of the time I try to access it so that I don’t get frustrated and find another site to use.
  • As someone who speaks a Latin-based language, I might want to run your software someday.
  • As a user, I want the driving directions to be the best 90% of the time and reasonable 99% of the time.

As you can see from these I was quite easily able to stick with the “As a <type of user>, I want <some goal>, so that <some reason>” template that I prefer for most user stories. I do this for a couple of reasons but want to comment further on only one of them here. Consider the example of the CTO constraining the team to use the existing orders database. (This was the real situation; the team was considering a second orders database that would be sychronized at night. The CTO overheard this and said “no!”) If we wrote this requirement as simply “Must use existing orders database” it would be entirely possible that a few months down the road we wouldn’t remember why we should be constrained in that way. We’d ask the product owner if she cared if we used a secondary database, and she’d say she had no objections. And we’d make a mistake of using one. Embedding the person who wants something can be very useful.

But, you should be careful not to get obsessed with that template. It’s a thinking tool only. Trying to put a constraint into this template is a good exercise as it helps make sure you understand who wants what and why. If you end up with a confusingly worded statement, drop the template. If you can’t find a way to word the constraint, just write the constraint in whatever way feels natural

Posted in Agile Planning, Sprint Artifacts | 20 Comments »

Advantages of the “As a user, I want” user story template

Saturday, April 26th, 2008

In my user stories book and in all my training and conference sessions on user stories I advocate writing user stories in the form of “As a <type of user>, I want <some goal> so that <some reason>.” While I consider the so-that clause optional, I really like this template.

At a recent conference, someone asked me why. Because I get that question fairly often I want to give three reasons why here:

Reason 1
Something significant and I’m tempted to say magical happens when requirements are put in the first person. Obviously by saying “As a such-and-such, I want….” you can see how the person’s mind goes instantly to imagining he or she is a such-and-such. As for the magic, Paul McCartney was interviewed and asked about why the Beatles songs were so amazingly popular. One of his responses was that their songs were among the first to use a lot of pronouns. Think about it: She Loves You, I Wanna Hold Your Hand, I Saw Her Standing There, I Am The Walrus, Baby You Can Drive My Car, etc. His point was that these helped people more closely identify with the songs. I tried briefly to find a source for this interview tonight and the closest I found was this. The information in that reference fits my recollection of hearing McCartney says this during a radio interview in 1973 or 74 that I assume was recording when the Beatles were together.

Reason Two
Having a structure to the stories actually helps the product owner prioritize. If the product backlog is a jumble of things like Fix exception handing, Let users make reservations, Users want to see photos, Show room size options, and so on, the product owner has to work harder to understand what the feature is, who benefits from it, and what the value of it is.

Reason Three
I’ve heard an argument that writing stories with this template actually suppresses the information content of the story because there is so much boilerplate in the text. If you find that true then correct it in how you present the story. I’ve seen backlogs in Word that present the boilerplate in grayed text with the unique parts in black. I’ve created product backlogs in Excel that use column headings to filter out the common text. Look and you’ll see what I mean:

sample user stories in Excel

Seriously take a look at the image above before continuing….I’ll wait……Please, really look at it before reading further…..

OK, here’s how I bet you read the spreadsheet. I bet that as you read most of the rows you added in the “As a…”, “I want….” and “so that….” text, possibly even by looking at the heading as you read across each row. I’ve experimented by asking people and this is what most people do. If that text is unnecessary, why do we mentally mouth the words to ourselves or even glance at the heading while reading the row? Perhaps it’s not so non-essential after all.

For now, and probably a long time to come, I’ll be sticking with the “As a <type of user>, I want <some goal> so that <some reason>” template for these and other reasons.

Posted in Sprint Artifacts | 65 Comments »

Writing User Stories for Back-end Systems

Monday, February 25th, 2008

I was asked recently how to go about writing user stories for a back-end financial system. This is an interesting example and is a question I get asked a lot, so I thought I should answer it here. This example brings up a couple of key interesting challenges:

  • While there may be users of the system they are not often not direct users (i.e., with hands on the keyboard waiting for something to happen)
  • The functionality is often larger than will fit in one iteration

So that we can deal with these challenges, let’s make up some more context for the example. Suppose our financial system takes in a lot of daily data and produces flat files that will be sent to banks and other partners at the end of the day. Some of the files are simple formats. Other files are in more involved formats with multiple record types within the file and possibly with multiple lines for some of the transactions. This would be a fairly standard batch-processing type application.

I want to write user stories in the template I recommend in the book: As a , I want so that . So, let’s deal with these challenges in order and first try to figure out who the user will be in our stories? Given the context provided above the user, is probably a bank or business partner. This will let us write stories like “As a bank, I want…” It’s entirely possible that we will want to get more specific and sometimes write stories for more specific users:

  • As a commercial bank, I want….
  • As a savings & loan, I want…
  • As the Bank of America, I want… (assuming we have some specific business partnership that provides BofA with unique functionality)

Now, what is it these banks want?

At a high level we can start out with some epics, perhaps like these:

  • As a bank, I want to receive a file showing all checks to be cleared so that I can debit and credit the right accounts.
  • As a bank, I want to receive a correctly formatted 5300 file so that I can adjust balances as appropriate.
  • As a bank, I want to receive a file showing the status of all resubmitted transactions so that I can update the database with new information.

(Note that I am liberally making up specific business rules or details. Presumably someone writing the real user stories could add real and relevant detail instead.)

First, notice it is OK to humanize the bank with “As a bank, I want…” Programmers do this all the time in conversation. “OK, suppose I’m the bank and you send me a 5300 file with a bad record. In that case, I’ll…”

As I said at the start of this post, one of the challenges in an application like this is that some of these user stories we just made up could be large. Suppose our mythical file format 5300 includes a header, three different record types, and a footer. We could break up the 5300 file user story above into things like:

  • As a bank, I want to receive a 5300 file with the correct header and footer so that I can process the file correctly.
  • As a bank, I want to receive a 5300 file with correctly formatted prearranged payment records so that I can process those correctly.
  • As a bank, I want to receive a 5300 file with correctly formatted deposit entry records so that I can process them.
  • As a bank, I want to receive a 5300 file with correctly formatted addendum records so that I can process them.

If those were still too big, I would find ways to split them smaller based on the specific formatting of the records. Suppose our deposit entry record type sometimes fits on one line but can also span multiple lines. In that case I could write these user stories:

  • As a bank, I want to receive a 5300 file with correctly formatted single-line deposit entry records so that I can process them.
  • As a bank, I want to receive a 5300 file with correctly formatted deposit entry records that include continuation lines so that I can process them.

Is the system “potentially shippable” after each of these user stories is delivered? Yes, it kind of is. While I’ll admit that we’re unlikely to find a bank that will take a 5300 file with only a header and a footer, it’s possible. Especially if we think of the situation in which the bank is simultaneously writing their own software to process the 5300 files we send them. Imagine meeting with the bank before the start of the next iteration and perhaps agreeing, “OK, in this iteration we’ll create some blank 5300 files with just headers and footers. But that will let us make sure that the communication problems are worked out, that you can read the files we write, and so on….” These stories also work well because they will likely fit with how the programmers will want to build the system.

Posted in Sprint Artifacts | 23 Comments »

Miscommunicating with the written word

Tuesday, May 22nd, 2007

What a wonderfully poor medium it is to communicate with written words. I’m sometimes amazed that we’re able to communicate meaning at all. Here are two good examples of how hard it is to communicate with written words.
A few weeks ago I was traveling and decided it was time to schedule another Certified ScrumMaster class. I emailed my assistant, Tonya, and said, “Please book the Hyatt in Denver for July 31-August 2.” A day or two later she emailed back saying, “The hotel is booked.” With that crossed off my mental to-do list I moved on to the next thing.

About two weeks later I’m again on the road and Tonya emails me saying, “Did you want me to find a different hotel in Denver or are you just not going to do that class?” I’m very confused because she’s told me the “hotel is booked.” Since that’s the case why is she asking me about booking a different hotel? We exchange a few more emails until I finally realize that her reply to me (“The hotel is booked”) did not mean “I’ve finished with that task; the hotel is booked.” It instead meant “The hotel is already booked by someone else; now what should I do?”

What’s interesting is to look back over the communication–nothing is wrong with what either of us typed into our emails except that we were each coming out the question from a completely different context.

Here’s a second example of how easy it is to miscommunicate: I’m in London this week teaching some classes for my good friends at Conchango. Since I can’t watch the basketball playoffs as I normally would this time of year I’ve been taking the opportunity to try to learn the rules to cricket. To someone with absolutely no prior exposure to the game it’s quite confusing especially as it seems to go on forever. I mentioned to my class today that I’m trying to figure the game out. One of the participants in the class shared with me the following instructions. These are apparently marketed as “Cricket Rules for Foreigners” throughout the UK:

You have two sides, one out in the field and one in. Each man that’s in the side that’s in goes out, and when he’s out he comes in and the next man goes in until he’s out. When they are all out, the side that’s out comes in and the side thats been in goes out and tries to get those coming in, out. Sometimes you get men still in and not out.

When a man goes out to go in, the men who are out try to get him out, and when he is out he goes in and the next man in goes out and goes in. There are two men called umpires who stay all out all the time and they decide when the men who are in are out. When both sides have been in and all the men have been out, and both sides have been out twice after all the men have been in, including those who are not out, that is the end of the game!

These rules are obviously intentionally obtuse. Notice how they are (probably) perfectly correct yet they say nothing about how to really play cricket. What strikes me is how similar these rules are to many requirements documents I’ve seen in the past–they may be accurate and perhaps clear to someone who already knows what is being said but they sure don’t convey any true understanding to the reader.

Posted in Musings | 12 Comments »