Customers
We determine requirements details just before they’re needed.
Traditional processes create a requirements document that—in theory—describes exactly how the software is supposed to work. This document is created by business analysts during an up-front requirements gathering phase.
But Agile teams don’t use phases, and story cards aren’t miniature requirements documents. How do they know what to build?
Agile teams prefer face-to-face communication, as “FACE-TO-FACE CONVERSATION” discussed. On-site customers—team members with the skill to represent buyers, users, and business stakeholders—are responsible for answering questions about requirements. They act as a living requirements document for the team. They communicate with the rest of the team via conversations, examples, and whiteboard sketches. This is faster and less error-prone than handing off documents, especially for complex topics. When developers need to understand a requirement, they just ask.
On-site customers are expected to figure out requirements just prior to being asked about them. The key to doing this successfully is expertise. Depending on the needs of your software, your team should include someone with product management skills, who figures out what to build and why; someone with domain expertise, who understands the nitty-gritty of the profession your software supports; someone with UX design skills, who studies users to understand their work and create productive UIs; and maybe even real customers, who provide context about what it’s like to use the software to do real work.
As an example, for an actuarial product I worked on, our product manager was an actuary, and the sponsors were the senior actuaries for the firm. For a chemical analysis product, the product manager had a Ph.D. in chemistry, we had a dedicated user experience designer, and the domain expert was an analytical chemist.
Even experts need to consider a variety of options and do research before making decisions. Customers, you can and should talk to buyers, users, and other stakeholders. (See “FEEDBACK AND ITERATION”.) Don’t just imagine how your software might be received: go find out. Ask questions, conduct experiments, and show off working software.
You’re also free to involve other team members. For example, if you’re a UX designer considering user interface possibilities, discussing them with the team’s programmers can help you strike a balance between an impressive UI and low implementation cost.
Customers decide for themselves how to remember what they’ve learned and decided. Whatever you use, treat them as temporary notes. All that matters is that on-site customers can collaborate with one another. If you end up needing permanent notes or formal documentation, they come later, as described in “Documentation”.
Although Agile teams are supposed to be cross-functional and include people with genuine customer expertise, many organizations have trouble staffing their teams that way. Instead, they choose people to act as intermediaries between developers and people with expertise. For example, a business analyst might be chosen in place of a domain expert, and someone with no decision-making authority might be chosen in place of a product manager.
It’s tempting for people in this situation to become gatekeepers, acting as a go-between and interpreting experts’ statements. Don’t make that mistake. If your on-site customers aren’t experts, then they need to facilitate conversations between the team and the experts, so everyone on the team can learn directly from the source. Then the team works together to incrementally flesh out requirements, as I’ll describe in a moment.
Sometimes, your team will be composed entirely of developers. The situation is similar: some members of the team facilitate conversations with experts, and the whole team works together on requirements.
Customers, work on requirements incrementally, in parallel with the rest of the team’s work, not in an up-front requirements gathering phase. This makes your work easier and ensures the rest of the team won’t have to wait for requirements analysis to complete before they get started.
As with the planning horizons of your adaptive plan, you’ll start with the big picture, but not a lot of detail, and figure out details as they’re needed. On-site customers work together to accomplish this work, typically with product managers focusing on the big picture and other on-site customers focusing on the details, as shown in Figure 8-3.
Identify the team’s purpose and visual plan from the beginning.
Prior to each planning game session, look at the visual plan and decide which increments will be the subject of the next planning game. Everyone with customer skills should get on the same page about why those increments are valuable and what it means for them to be finished. To save developers’ time, you can optionally break the increments down into smaller stories prior to the planning game, although you should be prepared to make changes during the planning game itself.
During the planning game, developers will ask questions about your expectations for increments and stories. Try to anticipate those questions and have answers ready. (Over time, you’ll learn what sorts of questions developers will ask.) A rough sketch of the visible aspects of the story might help. You may want to collaborate with a few developers in advance to prepare.
Figure out the details of each story just before developers start working on it. You should be able to tell when by looking at the visual plan. UX designers, create mock-ups that show what you expect the work to look like when it’s done. Domain experts, make sure you’re ready to provide examples of tricky domain concepts. Together, decide what it means for each story to be “done.”
While stories are under development, before they’re completely done, check to make sure they work the way you expect. You don’t need to exhaustively test the application—you should be able to rely on developers to test their work—but you should sit with developers and check areas where developers might think differently than you do. These areas include terminology, screen layout, and interactions between screen elements.
Prior to seeing the application in action, every conversation is theoretical. You can discuss options and costs with your developers, but until you have working software, everyone can only imagine how their choices will feel in practice. Only working software shows you what you’re really going to get.
Sometimes, developers will give you exactly what you asked for, but it won’t work as well in practice as you hoped. Other times, there will have been a miscommunication or misunderstanding. In either case, the solution is the same: talk with developers about making changes. You can even pair with developers as they work on fixes.
Many changes will be minor, and developers will usually be able to fix them by using the slack in the team’s schedule. If there are major changes, though, they may be too big to fix as part of the current story. This can happen even when the change seems minor from your perspective as a customer. Work with developers to create new stories for those changes. Before scheduling the stories into your visual plan, consider whether the value of the change is worth its cost.
As you continue to collaborate, developers will learn about your expectations for the software. Expect the number of changes you discover to decline over time.
Although Agile teams replace documentation with face-to-face communication, some documents still have value. They’re scheduled with a story, just like any other work. In some cases, updating documentation will be just one part of a larger story, but you can also have dedicated documentation stories, as discussed in “Documentation stories”.
Be careful not to introduce documentation just for the sake of documentation. As with everything the team does, make sure you’re clear about who the documentation benefits and why it’s valuable.
Product documentation is delivered to customers. Examples include user manuals, help pages, and API reference documentation. One team I worked with packaged up its test results into a formal document that helped its customers pass regulatory approval.
If your software doesn’t have any product documentation, you may still want to document what it does for the team’s future reference. It’s best to do so as part of each story, when people’s memories are fresh, as part of your team’s definition of “done.”
Operations documentation, also called runbooks, describes standard practices and procedures for a variety of situations, such as deploying the software, responding to alerts and outages, provisioning additional resources, and so forth.
Your organization may require you to create certain documents for governance or auditing purposes. Try to keep this documentation to a minimum, or meet the requirements by creatively repurposing things that have more value. For example, one team used automated acceptance tests, code coverage reports, and source control history to meet a traceability requirement.
Don’t assume audits require a particular process. They often require only that you have a process—of your choice—and can demonstrate that you followed it. This can give you more options for reducing governance documentation than you think. For example, rather than conducting formal code reviews, teams have used pair programming and commit comments to meet a “peer review” auditing requirement. Talk to audit groups early to build goodwill and create the opportunity for creative solutions.
Agile teams have a rich understanding of what they’re doing and why. But because they don’t communicate via documents, that understanding vanishes when the team disbands.
When your team is about to disband, or move to a different purpose, take some time to document what you’ve done. This is your software’s final increment. It’s like packing clothes into mothballs: it doesn’t help you now, but whoever inherits your work will be grateful you took the time. Your goal is to provide an overview that will let them sustain and maintain the code.
As-built documentation can take the form of written documents or video walkthroughs. It generally provides an overview of important concepts, such as architecture, design, and major features. The code and its tests document the details. Alistair Cockburn suggests recording a whiteboard conversation with an eloquent team member explaining the system to a programmer who isn’t familiar with it. Accompany the video with a table of contents that provides timestamps for each portion of the conversation.
Isn’t reducing the amount of documentation risky?
It could be. To reduce documentation, you have to replace it with some other forms of communication. That’s why Agile teams have on-site customers—to replace requirements documents. But you might still need to document what your team has built. If you think that’s valuable, create and prioritize a story for it, or include it in your definition of “done.”
Our customers don’t know what the team should build. What should we do?
Start with a clear, compelling purpose. If your on-site customers don’t know how to pursue that purpose, your team is missing important customer skills. In this case, you can use traditional requirements gathering techniques, such as [Wiegers1999], but you’re better off getting people with the skills you need. If you haven’t done so already, try chartering your team’s context and using that to better understand and advocate for the skills you need.
What if a customer review finds too many problems for us to deal with?
This is most likely to happen with a new team, before the team’s developers and customers have learned how to work together. In the short term, you’ll just need to write new stories for the changes needed.
Longer term, customers can spend more time each day talking with developers about their expectations and reviewing in-progress work. Mob programming is the ultimate expression of this idea. Customer/developer pairing is another option. With practice, you’ll learn to anticipate each other’s needs.
As a programmer, I’m offended by some of the things customers find in their reviews. They’re too nitpicky.
Things that can seem nitpicky to programmers—such as the color of the screen background, or a few pixels of alignment in the UI—represent polish and professionalism to customers. This goes both ways: some things that seem important to programmers, such as quality code and refactoring, often seem like unnecessary perfectionism to customers.
Rather than getting upset about these differences of perspective, try to learn what your customers care about and why. As you learn, you will anticipate your customers’ needs better, which will reduce the need to make changes.
This practice requires your team to include people who have the time and skill to work out requirements details. Without them, your team will struggle with insufficient and unclear requirements.
Don’t think of customer reviews as bug-hunting sessions. Developers should be able to produce code that’s nearly bug-free. Instead, the purpose of the review is to bring customers’ expectations and developers’ work into alignment.
Some organizations value written documents so highly that you can’t eliminate requirements documents. Talk with management about why those documents are important and whether direct communication can replace them. Perhaps as-built documentation is an acceptable compromise. If not, include stories for the required documents in your visual plan.
When customers work out requirements incrementally:
Developers work on established stories while customers figure out the details for future stories.
Customers have ready answers to requirements questions, which allows planning and development to proceed quickly and smoothly.
By the time a story is done, it reflects customers’ expectations.
Incremental requirements essentially takes the traditional up-front requirements gathering phase and spreads it out over the entire duration of software development. Rather than customers writing a document, handing it to developers, and then developers reading it, customers speak directly to developers exactly when details are needed.
People usually experiment with this underlying idea by watering it down. Most often, their team doesn’t include people with customer skills, so they drift back toward a phase-based approach and document handoffs. That decreases agility. If you’re looking for opportunities to experiment, experiment in the other direction: increase communication, increase expertise, and decrease handoffs. Mob programming is the result of one such experiment.
Kathy Sierra’s Badass: Making Users Awesome [Sierra2015] is a superb look at how to make products people love.