Planning successful projects: The User Story

Hey, that's not what I was thinking!

That's a very common complaint customers have with developers, when they receive the result of weeks or months of hard work. And it indicates a failure of planning.

We've found nothing that works better to avoid this result than to write up and discuss user stories in detail.

What's a user story? It's a description of the process a person goes through to get a specific result, and what happens along the way.

We regularly write user stories during planning to specify exactly what we plan to create. The user story consists of 3 main parts:

• The "Actor" -- who is the user who is interacting with the system?
• What exactly do they do?
• What is the result?

We find that by describing these processes at the outset, our customers gain a much clearer picture of how the finished project will operate, and so when the end result is delivered, they are not surprised by the result.

There's a standard graphical language for modeling software, called the Unified Modeling Language (the UML). It's composed of quite a few different types of diagrams, and each shop that uses it tends to use it in slightly different ways. This is a taste of how we interpret and use some of these elements to plan out projects.

After collecting as many user stories as we can think of, the next step is often to build one or more use case diagrams. Where user stories describe how a system will operate for a particular person, a use case has a more technical aim -- to represent more precisely how users interact with the system. These are graphical, and help to visualize the overall ways people will interact with the system. See an example use case diagram to the right.

Next, we develop a roadmap that identifies a sequence of development for the project. This roadmap synthesizes the user stories, the overall system requirements, the budget, and the customer's priorities into a plan of action, a sequence of sprints we identify to lead to the desired result.

Finally, as we begin each sprint we identify the user stories addressed in that sprint, breaking the work up into cases for development.

Here are a few example user stories:

• A staff user goes to the site, creates a news post, and publishes it. It shows up on the home page with a title, the first sentence, and a link to the full story.
• A staff user goes to the site, sees a typo on the page. She logs in, clicks the "edit" link for the page, corrects the typo, and saves. The copy is immediately updated on that page.
• A staff user wants to add a new image to the front page slideshow. She clicks the "Add new frontpage image" link on the staff menu, uploads an image, enters a caption, provides a link destination, and saves. The image is automatically resized and cropped, and added to the Javascript slideshow.
• A staff user creates an event page describing an upcoming event. She fills out the date and time for the event, selects the venue from a list of venues, pastes in the copy for the event from Word, clicks "Upload" to upload a photo from her computer, and saves. The event shows up in the list of upcoming events on the home page, on a calendar page with year/month/week/day views, and with an "Add to Google Calendar" link.
• A parent with a bright student goes to the site, wanting to know whether his child is gifted, what that means, and how your organization can help. He immediately sees a link that takes him to a list of Frequently Asked Questions, and finds answers to most of his questions.
• A parent has more questions about gifted-ness, and cannot find an appropriate answer on the FAQ page. He does a search but does not find a result. He finds an "Ask us a question" link that takes him to a friendly form he fills out, and asks a question. His question is emailed to a particular staff member for followup.
• A parent has heard about your program, and wants more information. He visits the site, sees an upcoming event, and clicks on it. It takes him to a page where he can sign up. The event staff gets notified that he has RSVPd.
• A parent wants to sign his child up for testing, and he visits your site. He finds a "Sign up for testing here" link, which takes him to a form. He fills out the preliminary intake information and clicks Save. The staff receive his registration.
• A staff member has received a registration for testing. She reviews the information, determines that it meets the qualification, and attaches the child to a reservation slot in the testing facility. The system automatically sends a congratulations mail to the parent with all necessary details.

User stories are a critical tool in our planning toolbox, but not the only one. We also make use of wire frames, activity diagrams, class diagrams, and more to describe the system we plan to build for a customer. The user story generally proves to be the most useful tool for communicating what we plan to build, however, because when we talk through them with a client, we often describe a story that the customer would like to go a different way.

This is one place that Drupal development differs from building custom sites from a framework or scratch -- there's almost always a "default" experience that's easy to get to, and it can take (a lot) more work to change that basic user story. Catching these differences at the outset can make a huge difference in terms of setting appropriate expectations. If we write a user story that reflects a workflow that is easy to attain in Drupal, and then discuss with the client, we can have much higher confidence that they understand how it will work when it's done. And if we understand the user story they would prefer to implement, we can create a much more realistic budget reflecting that understanding. Usually when we hit this situation, we start with the default experience, and put the "improved" user story on the backlog for a future sprint.

We'll be blogging about more of our planning techniques and tools in the future. Meanwhile, it's your turn... Please comment on what techniques you've found to be useful when planning projects, give us a good story about how planning or lack of planning turned out for you, or ask us a question about our process!