Archive for the ‘User Stories’ Category
Using the Right Medium
Filed under: Improving Software Development, Usability and Design, User Stories |
Comments (1) This post was co-written on Google Wave with my colleague Scott C. Reynolds and is a follow up to our previous post about good specification practices.
User Stories and Text
User stories and other text documents are the bread and butter of defining work, and we use them like crazy. Our story practice has evolved over time, and we have come to a place where we feel that, when used appropriately, our stories are very effective. For a deeper look at the guidelines we use to construct stories, I recommend you go check out Cat’s post on the subject. Go ahead. I’ll wait.
Okay, welcome back. Here’s the thing, stories and tasks are only part of the equation. Stories alone aren’t enough to define a system however, and trying to define everything in text is a fool’s task. (I’ve been that fool)
Pros: tell a story, capture detailed information
Cons: text is not good for everything
Using the Right Medium: Mockups
Mockups are a very useful tool when specifying details of how things should work. With stories, you really can’t add a lot of design and implementation details or the signal to noise ratio becomes too high and shit gets overlooked. A basic rule of thumb we employ on the team is "things that don’t get communicated well in text shouldn’t be forced into a text medium." Basically, if you’re going to try to describe the way something should look in a story, a) it’s probably not going to look the way you actually picture it b) that story is now noisy as crap and people are going to ignore more important parts. With a mockup, you don’t have to take forever to do a flashy, literal, perfect screenshot in Fireworks or anything; you can just drag and drop Balsamiq controls around and voila. Ya got an aesthetically pleasing mockup that humans go nuts over. In five minutes I can mock something up in front of a developer, explain how it works, and they are ready to go.
Another great thing about mockups is that they are extremely useful for getting user feedback on specs without distracting the user that "this is the final product, no more input." You can use a mockup to discuss workflow and layout without getting mired in fine-grained detail. The last time I was at the lab, I went back to my hotel room for a couple of hours and mocked up apps for 4 workspaces, brought them back to the supervisors, and was able to get plenty of good feedback and make edits right there in front of them. Gold.
Pros: Time-saver, gives the gist of what you want, keeps your stories clean while still conveying what you want, good to show to users.
Cons: Can fall into the trap of putting everything on a mockup just like you would put everything into a story and it’s inappropriate
Using the Right Medium: High Fidelity Design
How easy is it to develop from what basically amounts to a screenshot? You know exactly how everything should look, you can strip images out, you don’t really have to think about it.
Wait a minute. There’s a red flag.
You don’t have to think about it? That’s a paddlin’. A high fidelity screenshot, while beautiful, robust, and easy to work from, gives developers a signal that this screen is a specification set in stone. They see what it needs to look like, they build it like that. It’s just like BDUF; the high level of detail and granularity means that people won’t think about what they’re actually building, they’ll just duplicate what they are given.
Pros: Hotness, high level of detail, easy to work from
Cons: Removes developer thought, can take a long time to create such a design
Using the Right Medium: Conversation and Whiteboarding
While each of these mediums has plenty of merit and many benefits, conversation and whiteboarding are my favorite methods of specifying work. There is nothing like having the team (or pertinent members) together, talking through the workflow of a feature/app, mapping out how everything works, doodling out a rough idea of what things are going to look like and how things will come together. It is so damned valuable to have the working group together, talking through how things are going to work and getting their input. While business analysts and managers can come together to specify the general nature of how things need to work, having different members of the team around will help to eke out edge cases or problems that may not have been thought of in original discussion.
Conversation is obviously important by itself too; user stories are written to leave plenty of room for conversation. If you lose communication on your team and people just go off to code in the dark, a lot of the intent and original specification is lost.
Pros: Mapping workflow, multiple sources of input, easy to sketch out an idea/easy to change an idea, whiteboarding is fun as shit, conversation fully fleshes out ideas
Cons: Easy to get lost if not captured appropriately
While we’ve clearly chosen a favorite medium, you really can’t use just one. Each medium has a lot to offer depending on the scenario you are working with, and just like any other thing, you have to use what works naturally for the team in context with what you are doing.
Some Good Specification Practices, or, I Am Out of Clever Titles
Filed under: Improving Software Development, User Stories | Tags: agile, gemba, specifications
Comments (4) This post was co-written on Google Wave with my colleague Scott C. Reynolds, who makes me insane every day. It is part of his How We Do Things series.
Where We Came From
We began our large LIS project in late 2004, starting with about 6 full months of writing specifications and designing the database. We created reams of documentation for each application complete with use cases that we knew we wouldn’t even implement until after the first version was released (sidebar: some of those still haven’t been done). We defined more than 100 tables of heavily normalized database schema. Before one line of code was written, we had spent six months of project budget.
As development continued on the project we found ourselves diverging from the specifications that had been created. The documents became little more than a roadmap, with the bold headers on functional groups and the basic usage stories becoming the guidelines that we followed. Much of the detailed specification and database schema went out the window as the system took shape and people began to see and give feedback on what was being produced. Too much specification gave us a false sense of "doing it right" and led us down many wrong paths. Balancing rework with completing planned features became a costly chore.
By the time the project was complete, it was clear that much of that up-front work had been wasted time and money. Had we top-lined the major milestones of such a large project, detailed a small set of functionality, and started developing iteratively, the system would have taken form much sooner, allowing for a tighter feedback loop and much less overall waste.
How We Do It Now
Lessons learned, we set about improving how we do specification. Scott already talked a little about this in the posts on planning, so please review those if you haven’t seen them yet (here and here).
When planning a new project of any size, we take an iterative approach. We start at a very high level, and strive to understand the goals of the project. What need does it serve? Who will be using it? Are we competing with something else for market share? Is there a strategic timeline? What’s the corporate vision here? What are the bullet points? We will fill in details later. We only want broad targets to guide us further.
When we get closer to development, we start to identify smaller chunks of functionality within each of those broad areas. This is still pretty high level, but done by business analysts and management on the IT team. We start to identify MMFs (minimal marketable features) and group them up in order of importance to help determine next steps.
MMFs in hand, we take the first one and start defining it further. This is where the information from the planning post comes in. We start to write stories (Cat has a great post detailing how to build effective stories). The other information gathered to this point sits dormant, with as little specification work done as possible, until such time as we are getting closer to working on it.
Over time, and only as needed, we put more and more specification on the system, and this is done in parallel with development. In fact, often the most specific information can only surface during development of those features, as they take shape, and as we understand how users will react. Specification should be every bit as iterative as coding.
Reduced to its essence, we JIT specification at many levels to allow maximum flexibility to change direction with minimal wasted work.
Gemba As an Essential Part of Specification
Lean has a concept of the gemba attitude and genchi genbutsu; essentially, being in the place where the action happens. Developers and business analysts have to work with the domain experts, in the place where the work happens, and observe the true workflows in place before hoping to design a system to support them. You cannot get this information from sit down meetings and emails with domain experts. You must go and see for yourself, or you will miss things.
It’s often the case that a team relies on "domain experts" to provide them with the specifications they need to build software. This is the BDUF way – gather in committee and have the all-knowing user tell you what to build. Fail.
My Experience With Gemba
Our dev team works out of the corporate office in Florida, while the actual laboratory is located in upstate New York. As a result, it is often an exercise of the imagination to figure out the best way to create things for them. Before I visited the lab, I relied on information from others, emails back and forth to the lab crews working all weird hours of the night, and my knowledge of the applications currently in existence. I really only ever got half the picture, and it was difficult to ensure that the things I was specifying would fit into the lab users workflow well without actually knowing what was going on up there. When I visited the lab my whole world was changed. Actually seeing how users interacted with the software and seeing ways they would work around what we didn’t have (open Excel or Word documents on their desktop, a wall covered in post-it notes). Just from walking around talking to people for 2 days, I probably got 50 requests. And they never would have asked for them; they would have just kept suffering. Being there showed me everything about how they worked and a million ways I could improve their lives. The experience was invaluable to both me and them, and each subsequent trip has just improved my knowledge of the way we work and the way they interact with our software.
~Cat
There is no substitute for a certain amount of domain expertise being resident in the team room. Your domain experts are experts only in their domain. They may know the workings of a histology laboratory inside and out, but if you ask them to design a system to support that lab, they’ll come back with something that looks an awful lot like excel and post-it notes.
Yes, this is real. Yes, I died a little inside.
In the next post we will talk specifically about the tools and techniques we use to specify work, and how we combine them to form complete pictures of a system (spoiler alert: it ain’t just stories).
Plays Well With Others: Communicate or Die Trying.
Filed under: Fix Your Damned Life., Improving Software Development, User Stories | Tags: agile, communication, iterative
Leave a Comment So you’ve written some clear and concise user stories with robust and clean acceptance criteria. Good job.
You’re not done.
Because user stories are placeholders for conversation, simply writing them (no matter how fancy and thorough they are) is not enough. You need to follow through and talk with your team about what the stories entail. On our team, Wednesday is Demo Day. We do a demo of what has been developed so far for our major project, go through screens that have been designed to make sure everyone agrees with the design and functionality (and to make sure they understand what needs to be built), and go through the next MMF to be developed. At this stage people can interject with additional acceptance criteria that are needed, any concerns they have for the legality or complexity of the system, or anything else they need to voice about the upcoming work. It’s a great way to make sure everyone is on the same page and have a pretty good understanding as a team about the project as a whole, but even that is not enough.
Last weekend I was emailing back and forth with one of our developers regarding a particular story…the story was fairly confusing, partially because of the way it was written and partially because it is just a confusing piece of functionality. In the end (after maybe a dozen emails) we realized we needed a higher bandwidth conversation and input from others to really get this story locked in. When demo time came on Wednesday I found out another developer had taken and worked on the story by himself and the one I had spoken with had not ended up working on it at all. As the demo went on it became apparent that the entire thing was completely wrong. Several days of development time had now been lost on this project and we would have to scrap all of that functionality and start over. This is waste. Waste is the enemy, to be sacrificed on the altar of agile on the betrayer moon. Appropriate communication between myself and the team could have avoided this, and this example will serve as a lesson in the future (I hope).
Communication is really the key to everything. Software development has gotten so good and improved so much because of all of the communication that happens now. Think about how effective pair programming and user stories are as opposed to one dev holing up in a room with a use case and cranking something out. Being able to communicate effectively will improve your team and your product, make releases go smoother, and in general keep your life together. In the past year I have had to make a lot of changes to my life and improving my communication skills (inside and outside of work) has been the best thing I’ve ever done. If you are thrashing and can’t seem to find a good place to start making improvements, I strongly suggest taking a look at how you communicate and seeing how you can improve that.
Acceptance Criteria: Won’t Save You From the Zombie Apocalypse, But Still Useful
Filed under: User Stories | Tags: acceptance criteria, effective, specifications, User Stories
Comments (4) Acceptance criteria are a very important part of user stories. While the story itself tells you what a user needs, the acceptance criteria give it context. You get the business need and a set of statements describing the customer’s expectations so that you can better ensure their acceptance of the final product.
So, let’s take that Jaws example again.
As an oceanographer I need to cut open this shark so that I can see if that little Kintner boy is inside.
One of my developers might just rush through to work on this and cut it open right there on the dock. THAT IS A FAIL. That is not the time or the place to perform some kind of a half-assed autopsy on a fish… And I’m not going to stand here and see that thing cut open and see that little Kintner boy spill out all over the dock.
Maybe you give it a little clarification.
As an oceanographer I need to cut open this shark so that I can see if that little Kintner boy is inside.
-do not cut open on dock
Huzzah! Some specification! Now when the developers come to me to talk about this story and complain about having to drag a two-ton fish elsewhere to clean the license plates out of it, I can tell them why it’s a bad idea to rush into this one. To look at this from an actual software perspective and stop talking about sharks for five damned minutes, let’s look at this example:
As a lab clerk I need to be able to add a referring physician to a case so that the diagnostic results can be sent to all appropriate parties.
- user should be able to select referring physician from a list of physicians associated with the account
- user should be able to add new if physician is not available
This is pretty good acceptance criteria. The story is clear enough, saying that they need to be able to add a referring physician to the case, but the acceptance criteria specify how they get that referring physician. There is going to be a list of physicians associated with the account, so a user can choose from there. If we made them type it in each time, it would be hella wasteful and a poor use of their time. Choosing from a list dramatically speeds up their process and avoids QA issues later when they’ve typed the name incorrectly (all. the. time.). But what if the physician is not on the list, you ask? Why, the user can add a new one! Fantastic. The lab clerk can now quickly add a referring physician to this case without a) stopping to have someone add a new physician in the database or b) manually entering physician data for each physician they want to add.
Now this acceptance criteria has given us something very valuable: testability. With more context to this story, our QA team has more to verify and more scenarios to run through. They know that they need to test whether or not there is a list of physicians associated with an account, that a user can select one from that list, that a user can add a new one, and that a new physician added should be automatically associated with that account to appear in the list later (by virtue of being added in line to that case which belonged to that account). We have given this story context and testability, and I don’t think developers would have any problems building this story out. Additionally, the developers will be able to write better tests for the story as they are developing it. It gives the developers a benchmark to hit before they pass a story off as code complete. Testability is really an overloaded term that includes “benchmarks against which we can test our expectations.”
Now, be careful. Acceptance criteria can get ugly and unwieldy fast. You’ll start specifying things like “user should be able to press button to access report,” “there should be a save button that writes the referring physician to the database,” or “referring physicians should be linked by ID to accounts.” These are classic rookie mistakes. Acceptance criteria should not specify design; it should specify outcome. If there is some very specific design you would like to see, mock it up and attach it to the story. (Balsamiq [www.balsamiq.com] is a great mockup tool.) The second example of suck that I gave was a classic example of overspecification. This is something that happens all too often when writing out acceptance criteria. Read back through your criteria, and if something makes you say “well, DUH,” then it’s just noise and the developers don’t need to see it. Keep your criteria clean and simple and to the point. Noise reduces signal. Noise is bad. The last example is another mistake that is made all too often; specifying implementation details. You are writing the story from the POV of a user; leave the implementation details to the developers. This is not to say that you shouldn’t always leave out implementation details; sometimes things are necessary to make sure everything fits together. Find the sweet spots between all that crap you want to put in there and the stuff that really needs to be in there. It takes time, and I am still guilty of all of those things, but practice makes perfect (or so They tell me).
One of the best things that has happened to our acceptance criteria is involving the developers. When we do team planning the developers and QA team are bound to catch things that I have missed. You won’t always get everything right off the bat and you might not get it all yourself; collaborating with your team will help to ensure that you’ve caught everything. Meeting with your team just before time of development to discuss things will make sure that you have all of the requirements correct and that you will have all of the information. If you meet early on, requirements may change and your customer might decide they want something completely different (all. the. time.). Specifying close to time of development will ensure that everything is as accurate as it can be, to the knowledge of everyone involved. It’s perfectly acceptable to see the acceptance criteria grow during all phases of development. New information will surface as the team looks at and implements the story, and new expectations will be set. This is ok, and good, and desired because it means the team is coming together to ensure delivery of quality systems.
What acceptance criteria should not be:
- Design details
- Implementation details
- System language
- Overspecification/noise
What acceptance criteria should be:
- measurable
- testable
- descriptive of outcomes > implementation
- individually realistic and realistic as a group
- expectations (especially for a customer)
Not all of these things will work right for your team. Maybe you need some implementation details in your criteria. Maybe a little system language is necessary. That’s ok. One thing I have learned (and still hate) is: “it depends.” Everything is subjective depending on how your team is, things vary project or project (or even story to story), and it’s an uphill battle to hit the nail on the head every time. Take a deep breath, use your best judgment, and refactor it til it’s good.
Constructing Effective User Stories, or, My User Stories Bring All the Boys to the Yard
User stories are…
And this is where I get stuck. I’ve been so enveloped in writing user stories for the past year that I seem to have forgotten the basics. I’ve forgotten how I got to where I am now. When I started my position as a business analyst, my knowledge with software was…limited, to put it nicely. I didn’t have a damned clue about what I was doing. And The Google couldn’t help me either. Sure, I found some things, but everything I found made me look up something else. Everything was written a tier or two above where I needed it to be. I needed a really good starting point to kick me off but everything just skipped over that valley of basic knowledge and into the stuff that people really want to read.
So let me try to start from the beginning.
User stories are meant to capture the essence of the business value of a system, and are written in everyday language. For example:
As an oceanographer I need to cut open this shark so that I can see if that little Kintner boy is inside.
Ok, this is not a software requirement per se, but I am watching Jaws and it is shark week (love!), so deal with it. Here is a real user story:
As a nurse I need to be able to set my default location so that I am viewing my preferred data when I log in to the Nursing Station app.
Here is the breakdown of that story, and the basic format for user stories:
As a [role] I need [feature] so that [business value].
The nurse is the user who will be using the Nursing Station app. She needs the ability to set her default location so that she won’t have to waste time setting or selecting a location upon each login to the app. The business value implied here is that she won’t be wasting time doing this and can instead get some actual work done fast and not hate on my software for being unusable.
Depending on how long you’ve been writing user stories, you may or may not have learned a very true, key fact: users get in the way. They don’t know what they want but they will be damned sure to tell you. You will hate it. Do not count them out. Regardless of the way they present themselves, you need to come at it with the mindset to figure out the actual need there. If they are nagging you for a button or a field to enter a number, determine why they need it. If they just want it because of the way it looks or for an insignificant value/one that may a) mess with the rest of the software or b) tack a lot of development time on, probably don’t just give into their needs (in the long term they will start yelling about how long it’s taking, and when you throw that “you needed this button” back in their faces they are none too happy). Figure out why they want what they want, what purpose it serves, and if it works for all of the people who will be using the software. We don’t write code for edge cases, we make it work with edge cases.
The INVEST model
The INVEST model is the shit. It is one of the best things I have discovered for improving my user stories. This blog (http://www.agile-software-development.com/2008/04/writing-good-user-stories.html) has a really great summary of the INVEST model, which I will expound upon here:
Independent: User stories should be as independent as possible (don’t put something about a link in one story and then separate the link functionality; you’d have a dead link if the sprint wrapped and the complementary story did not get completed)
This is something I have really improved upon in my last year as BusinessCat.
1. Making stories more atomic means less of a chance for things to get tangled up and confused
2. That dead link thing? Yeah that happens. Be careful and make sure all of your stories and acceptance criteria are complete. See my thoughts on MMFs at the end of this beast.
Negotiable: User stories are not a contract; they are reminders for the team to discuss and collaborate to clarify the details near time of development
What a user story really is is a placeholder for a conversation. We’ve gotten away from writing strict, rigid use cases and into these user stories, which are much better for the way the business world really works. By writing a user story this way, I am opening up a higher bandwidth conversation. Instead of a developer just reading what I have and doing it word for word, now we can talk about things and make sure everyone is on the same page and fully understands the business value and the needs of the user. I like that Kelly specified “near time of development” though; that’s one thing you’ll always find: CHANGE IS A CONSTANT. Friggin annoying, but it is inevitable. The closer to development time you talk about something the more likely it is that you’ll have the best information and the most clarity on the item.
“A fundamental lean principle is to delay decisions until the last possible moment so you can make the most informed decision possible.” – Mary Poppendieck, Lean Software Development: An Agile Toolkit
Valuable: User stories should be valuable to the user and written in user language
User stories are user stories. So put on a user hat and write it. You should never have anything like this in a story:
“title attribute displaying formatted address when user mouses over”
I got stuck putting this in a story the other day by a higher-up and I was really mad at myself for letting it in there. Yes, it will tell the developer what to do, but no user would write that. Leave implementation details to the developer. Describe the desired result, not the implementation. What it should say is:
“display tooltip when hovering over address”
There is still a little bit of implementation language in this, but it’s an abstraction higher than spelling out the html. Sometimes you can only refactor so far; I would be happy to leave this in one of our stories.
When I have the conversation with my developers we can talk about this to make sure they understand it, but it’s terrible to have the former in a user story. If I don’t understand it, I shouldn’t be writing it. And I am the user.
Estimable: User stories need to be possible to estimate; they need to provide enough information to estimate, without being too detailed
This goes back to stories being atomic. When we write stories on my team, we make them no larger than 3 days worth of work. If the developers do not agree that it will take three days or less, it’s time to refactor. This isn’t ideal for every team, but we have worked to become a sophisticated enough team that we can work like this. Plus, it’s ideal. If you have massive stories there is more chance for stuff to get lost or overlooked, things will be harder to test, and general craposity will ensue. In summation: Yer doin it wrong.
Small: User stories should be small. Not too small. But not too big.
See above. D’oh. Additionally, don’t be discouraged when you need to refactor your stories a bah-zillion times to get them to be more atomic. You will not get it right at first (I sure as hell didn’t), and a continuous improvement mindset is an absolute necessity to success. Be willing to give it a go, observe the results, and adjust, as an ongoing process.
Testable: Need to be worded in a way that is testable and not too subjective; must provide clear details of how the user story will be tested
When QA tests, they run through many, many different scenarios. If your stories are too rigid they won’t necessarily hit all of the possible scenarios and edge cases. Be sure that you leave the story open enough that people will think about all of the ways the feature will be used.
We recently starting using MMFs (“A minimum marketable feature is the smallest possible set of functionality that, by itself, has value in the marketplace.” – James Shore [http://jamesshore.com/Blog]), which has helped us immensely with keeping things together and not losing track of things. It also makes our releases easy peasy and we don’t miss things (dead links?), etc. If your stories seem to be less cohesive than you would like or you find that things get missed, MMFs might be the right route for you to take and I would recommend using that format (or at the very least checking it out and seeing if it’s for you).
For a little further reading, I would recommend checking out Ron Jeffries’ post on the three C’s: Card, Conversation, Confirmation (http://www.xprogramming.com/xpmag/expCardConversationConfirmation). He’s got some great points that he makes better than I could, so if you’re interested in more detail about writing effective user stories that’s a good next stop.
