AoAD2 Practice: Incremental Requirements

This is an excerpt from The Art of Agile Development, Second Edition. Visit the Second Edition home page for additional excerpts and more!

This excerpt is copyright 2007, 2021 by James Shore and Shane Warden. Although you are welcome to share this link, do not distribute or republish the content without James Shore’s express written permission.

Incremental Requirements


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?

The Living Requirements Document

Whole Team
Team Room
Real Customer Involvement

Agile teams prefer face-to-face communication, as the “Key Idea: Face-to-Face Conversation” sidebar 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.

Don’t just imagine how your software might be received: go find out.

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 the “Key Idea: Feedback and Iteration” sidebar.) 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 the “Documentation” section. continue reading, buy the book!

In this Section

  1. Incremental Requirements
    1. The Living Requirements Document
    2. When Experts Aren’t Part of the Team
    3. Work Incrementally
      1. Purpose and visual plan
      2. The planning game
      3. Mock-ups, customer examples, and completion criteria
      4. Customer review
    4. Documentation
      1. Product documentation
      2. Operations documentation
      3. Governance documentation
      4. As-built documentation
    5. Questions
    6. Prerequisites
    7. Indicators
    8. Alternatives and Experiments
    9. Further Reading

Discuss the book on the AoAD2 mailing list or Discord server. For videos and interviews regarding the book, see the book club archive.

For more excerpts from the book, see the Second Edition home page.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.