Wednesday, May 27, 2009

How do I track requirements?

One of the questions I get via Twitter and comments is how do I track requirements. When I came into a job that had gathering requirements as a part of its duties, I got the duties without any sort of best practices (one of the quirks about coming onto a contract that was still dewy faced). People gathered them how they felt it suited them and the customer, giving me a lot of leeway as to how I felt I should do it.

I had a lot of false starts, but we've come to something that works for the document wizards, developers, and customers.

But Framework X does that out of the box!

The first method was not to gather requirements at all, because the developers had found the magic bullet we needed. All I had to do was write up what the current framework did.

Oh my god. Do NOT fall for this.

Unless the requirement is stupidly simple, you will almost always have to do customization. Actually, if the requirement is stupidly simple, it's guaranteed that one thing will always pop up:

You haven't gathered all the requirements.

So many times we'd set up some naked framework, skin it with something we downloaded and, if we were feeling artsy, blinged out with a new header image or something, and hand it over to the customer. And the customer would poke at it. Best case, we'd hear back from them that it wasn't quite what they were looking for. Worst case?

We'd never hear from them again.

Quiet customers are not always a good sign. We'd check back after a few weeks, only to see our wunderprodukt laying fallow, collecting dust and not even generating a system log anymore.

So, even if we have the perfect solution, I make sure to gather requirements. I show the customer the framework and sit with them while we poke at it and look at everything it does... and keep an ear out for what it doesn't do.

Tickets to requirements

All requirements must be in a ticket. Every last one of them. If it's something that's going to generate code, text, graphics, CSS, or even just some thinking, it goes into a ticket. Keeping requirements in a document is a joke. The document is useful for keeping a nice concise record of the requirements somewhere. It's like a tar file. You don't work off the tar file. You keep it as an archive.

One of the keys parts of this is limiting the number of requirements/tickets. The poor dev/tech lead brain can only retain so much at once (too many movie quotes and such rattling around in there).

Body language

There's a danger to keeping everything in tickets, however.


I appreciate the need for comments, but sometimes, I hate the little buggers. They're a fetid breeding ground for cross-communication, requirement creep, and pure paradoxes (The cat must be both dead and alive at the same time. You can do that in Python, right? If not, we should see if the Java guys can do it!)

For that reason, I laid down the law that if you really, really love that new idea of yours, it had better go in the body of the ticket. Comments are kind of like fireflies in a jar. Nice to look at for a while, but they're going to die pretty quick.

User stories and interactions

I love interactions. I really do. An interaction might go like this:

Jane goes to her widget maker and logs in. She is taken to the home page. There, she clicks on "Make a new widget"

A box pops up, allowing her to enter in all the details of the widget. She notices that the "Make my widget" button is inactive. Once she has filled in all the required fields for her widget, the button becomes active. She clicks it.

The box closes, and her widget is now featured as a line of text under "My widgets".

I have a two rules about interactions:

If I don't say the user goes to a new page, they don't.
If I don't say a user has to click to get to a new page, they don't.

Sometimes it takes running through a few to realize how many functions have to be exposed, and coming up with a sensible to expose functionality without drowning the user in them.

A nice thing about interactions is that more than one person can use them. Developers can use them to see what needs to be put where. Designers can use them to condense and organize functionality (and then make it awfully pretty). Even customers can read them to make sure that we're still in line with their vision.

Two week dashes/scrums

Sometimes a project hands us more requirements than our poor heads can handle at once, but isn't handing us a ton of time. In that case, I usually break up requirements into small, two week chunks. One scrum, we might focus on a certain user type's interactions. Another, ACL. Another, authentication. One of the last ones, implementing design.

The two week scrums help us get alarm bells early that something isn't going right, and help focus our resources on one problem. There's always going to be one guy that is more into authentication than stupid templates, and one that wants to do cool CSS rather than sigh endlessly over optimization. If one resource is hopelessly bored, we can always release him for another project until something cool comes up again.

At the end of the two weeks, we can look at what was done, what wasn't done, and determine if we need a second scrum, or if those hanging reqs are looking a bit silly now and should just be canned.

None of the above leads to a perfect system, which is why I tend to switch around from project to project. If you get too used to where you can sweep the crumbs, you end up with pockets of dust bunnies and petrified Pop Tarts that can lead to a distressed customer, a stressed out PM, and some sad-faced devs looking at their weekend disappearing.


Anonymous said...

I think interactions are fundamental: most of the "normal people" do not differentiate between "user experience" and "functionality", so if you provide outstanding functionality with a frustrating user experience, the customer is going to complain that "the functionality isn't there".

Probably, formalizing a "language" in which to model an UI and interactions which is understandable by anyone and unambiguous can help dramatically in avoiding circling.

Martin Aspeli said...

Great post. :-)

Sometimes, having a fully featured platform can make requirements management difficult, for three reasons:

1) Delivering a requirement requires some customisation, but this is either ignored or mis-estimated.

2) The platform does more than your requirements state. There may be work to turn off of things, working out what exactly and how much effort is required is difficult. These types of requirements tend to come in later, when people start testing the system, so they're difficult to estimate for.

3) Even if you want the out-of-the-box functionality (which may happen because the requirement is "I want this feature of Plone", explicitly), you still need to track it and test it. Plone could have a bug in the version you're using, or something you did elsewhere could've had a negative impact on this feature. So, even things that are provided out of the box require an effort estimate and planning and acceptance testing.

On your other point, about comments, you are absolutely right. As a rule of thumb, a developer is only going to read the full "thread" for a requirement once. In all day-to-day activities, he or she will look at the title only, and this needs to be enough. That's why I'm a big fan of user stories:

"As an [actor], I can [feature], so that [business value]"

These types of requirements have a number of advantages:

- They're short enough to talk about and remember
- They're descriptive
- They identify the who, the what and the why in a concise statement
- They are deliverables, not tasks, so you can measure when they've been completed
- They can be estimated with story points, which is a great way to get decent estimates quickly