Topic: Requirements

Design Documentation

documentation
Creative Commons License photo credit: theD40kid

A few years ago, I worked on a team that was trying to move the business side away from the waterfall method into more of an agile approach so there wouldn’t be such a disconnect between design and development. Since there was no blueprint on how design could be done in an agile fashion, resistance was very high. One of the major sticking points, however, was in documenting requirements. The business side controlled the process which meant no one could see or review the requirements until they were released by the analyst. In a world view of us vs. them, collaboration was not very high on their list.

Collaboration, however, is high on the list for agile development. So, how to resolve this conundrum and begin to merge the two teams. Continue reading »

Bugs can’t be estimated

group estimation

In an earlier post about the benefits of Agile and Scrum, I made a statement that bugs by their nature are not the same as normal features, and I wanted to take a moment to try and make my point a little clearer. Bugs and estimation have been a hot topic with us lately, but interestingly we are all working on different projects and actually have a slightly different take on the subject.

My definition of a bug is: A feature that was specified, and you attempted to deliver, but is not working according to your intentions. (ie. "I thought it WAS saving to the database")

Not a bug: A feature or variation that you hadn't intended to create in the first place. ("Oh, I didn't know it was supposed to do that when you clicked the back button")

And with that understanding I say "Bugs can't be estimated"
Continue reading »

Are You Building an Application or an Antique Web Framework?

1927 Ford Model T tudor
Creative Commons License photo credit: dave_7

A few years ago, a friend of mine asked me to help him estimating the conversion of a client/server application to the web. He came armed with a spreadsheet of features, I came armed with Ibuprofen and a red pen.

My usual approach to estimating involves breaking down the features into things that can be implemented by a pair of developers within a two week period. I give these a complexity factor of 1-5, then run them through an empirically derived formula to come up with an estimate in terms of person-iterations. (It's actually a little more complicated than that, but this is the main effort). Getting the count and size of these mini-features right is the key aspect of this technique. His spreadsheet had almost 300 features listed, and so we settled in for a day of fun.
Continue reading »

The Starting Line

Companies (and people) new to software development tend to think that projects start with development, as in writing the actual code, as in here’s my idea … when can I see it and btw, why am I paying you for time that you’re not coding. Most are not aware of the upfront work needed to get to the point of coding or, perhaps, even the value of it. After all, they gave you the idea so let’s see less talk and more coding.

What is some of that necessary work that’ll drive us towards development? The upfront work definitely includes requirements — the details that allow us to start writing the code. But even before the requirements are started, long before diving into the wireframes and user modeling, features list or user stories, projects need to begin with a business problem and a blue-sky idea on how to solve that problem. In short, the product concept.
Continue reading »

Writing Agile Requirements

The beginning of a project generates a lot of great ideas. But until a structure or cohesion is applied to these ideas, they end up being a loose collection of separate ideas with no direction. Writing agile requirements brings cohesion and direction to the noise. We've been continually improving user driven agile for a while now. Click through the presentation below to see the approach that works for us.

Definition of a Feature (Given … When … Then)

defining requirementsAt some point in their career, most everyone in software development has encountered the client who paints a very eloquent picture about their fantabulous idea that’s going to revolutionize the [insert industry vertical here]. However, as time goes on you realize the client’s staying at the 60,000 foot level, and while that may make for great conversation, it's less than ideal for actually developing something. The trick, then, is to get them to climb down into the trenches and define the details before you have to start writing the code.

At Pathfinder, we’ve been involving clients in creating business-driven scenarios to define a feature, i.e., what does ‘create accounts’ really mean. These scenarios walk through the different tasks of a feature and identify the expected behavior and outcome based on the user’s actions. Although they follow a specific format (context, events and outcomes), they are written in plain English that can be understood by all team members.
Continue reading »

Scrum defined in under 10 minutes

Hamid Shojaee from www.axosoft.com put together a great video to introduce the core concepts of scrum and Agile practices called "Scrum in under 10 minutes"

Get Adobe Flash player

I really like what he said particularly the focus on the importance and simplicity of the burndown chart which helps to :

  • Visually show the hours remaining, and help anyone see "are we there yet?"
  • Allows decision-makers to make adjustments if needed

A simple burndown chart quickly shows the impact of some of the most common efficiency killers or blockers

  1.    late-breaking requirements changes
  2.    waiting for business decision
  3.    waiting for tech. partner (ssl keys, ops. vendor, etc)

He mentioned the standup, but didn't cover the 3 questions (What did you do?, What are you going to do? What do you Need in order to accomplish it?), or the idea that only people that have work can speak (Chickens vs. pigs)

I also liked his take on bugs, that you should plan a sprint to tackle them, and any bugs that come up during a sprint should be tackled immediately.

That's actually something that a lot of teams struggle with, "How do you plan for and estimate the time necessary to fix bugs?"

I always say Bugs Can't be estimated. While you may be able to plan how much time you will allocate to working on bugs, you can't really estimate how long it will take to fix bugs unless you have already looked at them, and have figured out the problem. From my point of view its the "looking at it and figuring out what's wrong", that takes the longest, and is the part that needs to be accounted for.

How do you plan for bugs?
Do you let bugs accumulate and then have a final sprint before a Release where you tackle all of the bugs? (How would you know that you can fix all the bugs in time for the release?)

Do you tackle all High-Priority bugs as soon as they come up, and leave the medium and small priority bugs for later?

Do you have a 'zero-bug' policy, where you fix any bugs that are opened?

UPDATE: I've expanded on this discussion a little more in a new post Bugs Can't be estimated, and after having some discussions around how best to plan for bugs, I was asked to do a last minute Security Analysis, and I wrote a post about How to avoid the last minute security review, and I think that the planning part can actually apply to how you manage a big list of bugs as well.

What makes a good requirement document for an agile project

As a developer, I start from requirements. I have worn project management and business analyst 'hats' on many projects (but I am a geek, as I really enjoy the developer hat the most). My coworker, Alice Toth, has come up with a pretty awesome template and style of writing requirements that seems to be perfect for the agile development methodology. Too often, I see struggling projects struggle, because their requirements suck. I look at their "requirements" and they are nothing more than a picture with a bunch of notes. The developers have so many questions, and in general, all people involved (client, developers, BAs, IAs and testers) don't have a good understanding of the system as a whole, and what are the various personas that use the system.

I have worked on projects that have used Use Cases and Functional Specifications, but these never seem to convey all the necessary information for all involved. They tend to be very verbose, and they are really not fun to write, read or manage. A good requirement should tell each audience member exactly what the expected functionality is, and never generate a myriad of questions from all involved. It's often difficult to solicit information from a client, but documenting for developers should never be that hard. Here is a recap of what a good requirement is:

Continue reading »

Topics: ,

Testing

Let's have a little more compassion for the QA Team, eh?

Well, actually, the Design Team disguised as the QA Team.

The little frustrations, system and function failures result in a lot of dog-kicking, huge antacid and alcohol intake and a lot of whining. I begin to understand how little-person tossing may have started down under a few years ago. Obviously QA Teams at the pub got this trend started.

The academics have broken testing up into five or six TLAs (Three Letter Abbreviations designed by Consultants so they can charge more and use more buzzwords than normal people). You got your UAT (User Acceptance Test), your Unit Test, your Sanity Check, your boundary test, your Automated Regressive and Non-automated Regressive series (this means high school kids who click and chew gum while re-Ghosting machines) and on and on.

These labels are obviously created by people who don't do testing.

Us testers use language you shouldn't put on a blog.

This blog started because I had to do a complicated test three times today before I got the dang thing right.

I wrote the test script, had to change it four times because it wasn't really testing what I wanted it to test when I was writing it yesterday. Funny thing. I had the developer who created the function look it over for me. He said it was fine.

But each of those rewrites was one to three new database entries.

When I had it right and came to the end of the second phase of the three part test... the application didn't do what I wanted it to do. Totally unrelated to the test. ARGH!

I know.

You've been there, done that and have the tee-shirt.

Come to think about it, Our PM owes me a tee-shirt. 3XL, Ron, I've lost 45 pounds since 4/4.

Before I threw my laptop at the wall, I calmed myself by repeating the Tester's Mantra: If I didn't find it, the Client would.

The thing is, I don't mind writing Test Cases or even test scripts. I find writing them an interesting challenge. I also find doing them drudgery, akin to the constitutional prohibition against cruel and unusual punishment.

I wish I could get into the spirit of a real QA guy who thinks about these tests creatively and with wild abandon. You know, the fellow or gal who can think like a crazed end user ready to pounce on my poor application with abandon and relish.

Such folks are a treasure.

But with a small team, the lack budget for QA resources and the need to test major functionalities of a complex application, we Business Analysts, Information Architects, Project Managers and Receptionists will continue to click, type, spell check and screen capture.

And moan, groan and whine.

But it's gotta get done.

Oh, for the days when the BA and QA Lead managed the process and others did the work...

Another Way to Pair Program: Generating Requirements

The CTO (Chief Technical Officer) tells the BA (Business Analyst- me) and the IA (Information Architect) to pair program.

He's our boss' boss.

He's our Agile ubermensch (mensch is a Yiddish-Middle German word meaning, in this context, expert, coach, guide, all around super star; I don't know if it is in Modern German, but our CTO will tell me, he's fluent in German. I took Latin and Spanish).

We gotta do what he says.

I whine that I write faster than the IA.

The IA complains I can't do wireframes as fast as he does (true, VISIO isn't as easy as it looks, kids).

We are despondent and snarl at each other. Pitiful.

An idea.

How about we split the requirements in half. I pull the ones I wanna do, the IA grabs the more visually oriented ones. We write 'em up, do the wireframes and then have the other edit and comment on the other's work while we collaborate on the items we need to.

It allowed me to spit out the bug repairs like a machine gun and freed our IA into drafting wireframes and workflows he needed to do without slowing me down. While we edit the other fellow's stuff, we find small errors, ask some questions and significantly improve the requirements without turning them into novels.

The benefit was to the Developers who had very spiffy, concrete, succinct and directed requirements before the iteration started. They had time to read them, ask questions and begin their design work. The client was able to read them and sign off early making the sprint kick-off run smoothly.

The CTO gave his blessing.

And yeah, I started numbering the dang Business Rules to help the Developers, even though everything I ever learned about writing tells me non-hierarchal/unrelated lists should be bulleted. But it helps the developers refer to specific rules and my sense of technical writing dos and don'ts can suffer this arrow of outrageous fortune.

The Developers were not impressed. They like numbers. Especially ones with decimal points.

Turns out the PM (Project Manager) even likes the IBM-concentric deep diving numbering schemes of the 1970s. There's no accounting for taste, is there?

But I don't have to like it, do I?

It Starts with the User Story

Having recently been asked about the difference between a use case and a user story, I came up with this explanation:

Use cases detail the interactions between an actor and the system in a sequence of steps and are generally used to capture the functional requirements of a system before implementation. Because of their scope, i.e., they take in more exception scenarios, they can be too large to be used for iteration planning since they would be split across multiple iterations. Also, there is a bit of a learning curve to interpreting use cases which can leave the non-technical customer out in the cold.

A user story is a short description of a feature as told from the point of view of the user (generally your persona). They consist of one or two sentences written in the language of the user, and are used to estimate the degree of difficulty to implement (which ties in with iteration planning). At Pathfinder, we also include acceptance tests when we write the user story as a way to set out the criteria that determines when the story's goals have been met. Again, written in plain English so that both technical and non-technical team members understand what success means for that feature.

For our Ruby on Rails projects, we're writing our user stories in a format that'll help the developers convert them into automated tests using the Rails framework:

As a [role]
I want [feature]
so that [benefit]

From here we create the acceptance criteria, which we write as scenarios in a specific format (givens, events and outcomes) in order to help with writing the automated tests:

Scenario 1: Title
Given [context]
And [some more context]…
When  [event]
Then  [outcome]
And [another outcome]…

We'll then go on to create flow diagrams, requirements and wireframes to further flesh out the details of this feature, but it all begins with the User Story and Acceptance Tests.

We Don’t Need No Stinkin’ Requirements

The other day I was reviewing a statement of work for a potential project when the client came to  the line item allocating time for requirements. Oh, the client stated, we don't need to gather requirements. We do Agile development.

*Sigh* This myth of no requirements needed seems to be prevalent lately.

Well I hate to break the myth, but projects still need requirements regardless of the method used for development. The reality is you can’t create something unless you know what it needs to do. In order to know what it needs to do, you need requirements (business, technical and user).

The differences come in with the methods for gathering requirements. Some teams make requirements gathering the central activity, creating documentation detailing everything down to the nth degree before development begins. Other teams put less emphasis on knowing all beforehand and instead start with sketches or three sentence "stories", knowing that details will be filled in and added as the project progresses. Side note: make sure you have some way of documenting those hallway conversations because, yes, those are actually requirements gathering and it's good to keep a record somewhere accessible by the project team.

At the most basic level, the purpose of requirements is to define the problem you're trying to solve. Whether your team waits for a complete definition of the problem before starting development or starts with the basic outline depends on your development method. But you still need requirements. After all, if you don't define the problem, how do you know when you’ve solved it.

Not sure how to write requirements? Check out my colleague's post: Writing Requirements

Unanswered Questions of User Research

Luckily, formal usability testing offers us the opportunity of conducting a near-scientific study of stimulus and response. We're able to cull prospective users from a pool of particpants, and screen them against  a carefully chosen list of attributes, including gender, age, computer literacy, and other specific qualifications--much more discrimination than the "real world" of users and links and happenstance allows.

When it comes to initial requirements gathering, though, we often (in the words of Tennessee Williams), "depend upon the kindness of strangers." There are at least three types of early user researh/requirements gathering whose success often depends upon the enthusiasm or engagement of the client. It follows that this pool of resources must be evaluated through the filter of operative agendas. Here are three examples of user research that can be potentially valuable if all factors are considered.

1.  Subject matter experts - an incredibly valuable asset for building site or application content. Always keep in mind that the SME's time is constrained. Keep your questions open-ended, but focused on the task.

2. Stakeholder interviews - keep in mind that the client probably has an incentive to obtain "buy in" with these interviews. While much independent data can be garnered from these interviews, pay close attention to the client's needs and goals with these interviews.

3. "User" interviews - at an early stage in the project, these people are probably anticipated or target users. Don't lose track of capturing data to build personas and actual user scenarios.

Requirements Visualization, V1

At Pathfinder, we have developed some responses born of our collective experiences to the problem of huge requirements documents.

The problem is that on a complex project, a network of interdependent decisions is constructed, then shoehorned into an essentially linear document. While this functions as a form to analyze these problems, it's very [linear] nature makes it... well, boring! Even developers and designers are human!

The functional result is that it ends up as a doorstop somewhere in the office, or finds a quiet angle of repose near a bookshelf and no one ever reads it. These typically represent months of work by large, passionate teams and great expenditures. Not an ideal outcome.

What can prevent this? With all our focus on our favorite personas, and the scenarios we construct to walk them through, it is easy to forget that the person who was just handed 150 pages of your careful work is arguably your most important audience.

Take a moment and review that the order of the parts feels obvious. Make sure that the document has a clear and accessible structure. This means a contents page with content areas that have immediately understandable names. Even though it may seem unnecessary to you, having spent the last 4 months on it, a general overview that orients a first time reader is appreciated. This sets them up for the detailed decisions that follow. Starting someone in the middle of these processes, as I too often see, tends to make people glaze over and just make it up as they go.

Comprehension is more important than brevity here - at PFA, we find that annotated pictures are far more specific & engaging than trying to describe with only text things that can be easily shown. If that adds pages to the document, it is a small price if it gets read and understood. These visualizations do not need to be elaborate. In fact, we are facile at understanding abstracted representations - look at the drawing languages of cartoons. The messages are clear, despite the fact that Mickey has only three fingers or Charlie Brown has a single squiggle that stands for hair.

In sum, showing what you intend is powerful, yet doesn't need to be elaborate in production. The other side of the coin is to spend endless amounts of time illustrating a solution at the expense of more iterations, but that's another blog.

Launch: Pathfinder Newsletter

    Get a monthly update on best practices for delivering successful software.

    Subscribe via email


    Subscribe via RSS      RSS icon

Topics

Search

WordPress

Comments about this site: info@pathf.com