Where’s the Spec, the Big Picture, the Design?

These questions were recently asked on the XP group, in the context of a review of Mike Cohn’s User Stories Applied. The answers are a function of the whole project, not just User Stories.

The Question

On Tuesday, December 28, 2004, at 2:43:31 AM, Mattias Vannergard wrote:

  1. Where is the “Big Picture” kept when working with stories?
  2. Where does the design go?

(Same question as the reviewer on: http://www.stickyminds.com/r.asp?F=DBOOK_709.)


In the review referenced, the reviewer says that writing the stories down as a contiguous specification document is a good thing, and underlines that idea by saying that everybody should use some standards. Neither of these dictates is supported, and while the particular standard suggested by the reviewer may be appropriate to some projects, it is not appropriate to Agile projects.

Still, these are good questions. The answers require us to look at more of the aspects of an Agile project than just the User Stories. Every project is the sum of its parts, and an Agile project is no different. The cycle of needs, specifications, designs, and implementations is very rapid in an Agile project, less so in a more conventional “plan-driven” development cycle. An Agile project is delivering running tested features every week or so. That changes everything.

Communicating Inside the Project

An Agile project cannot be driven effectively by comprehensive specification documents: it is ready to begin development as soon as any important features are identified, so that waiting for a complete document is wasteful. It is this ability to start development sooner that helps an Agile project to deliver value sooner.

It might be thought to be a good idea to “grow” a comprehensive specification document as the project goes along. Such a document is of little value to the project team, since everything that can be written down in the document is already written down in the code and the tests, if the feature is already implemented, and will be more richly described by conversations and tests when it is scheduled for implementation. Therefore “growing” such a document is also wasteful.

As for the “big picture”, the team can keep it wherever they want: the most important place to have the big picture is in people’s heads. This means that a big picture consisting of a few hundred pages of paper simply won’t fit — and isn’t really a “big picture” but instead a lot of details.

An Agile team creates its big picture dynamically, with lots of conversation and the creation of whatever documents it needs. Because such a team ideally works together in a single room, much of this picture is represented by conversations, supported by pictures on the whiteboard or posted on the walls. Teams using the substantially inferior approach of working in separate offices or countries try to accommodate this need with more documentation. This is just as effective as replacing hugs from your loved one with a detailed document describing their attributes and affection: it’s better than nothing but ultimately unsatisfying.

Because an Agile team is creating the system iteratively and incrementally, they invariably need intensive and high-quality testing. The iterative nature of the process calls out strongly for automated testing, since a manual testing effort will quickly become swamped by the need to retest everything every week or two. Therefore, there will be automated tests for every detailed feature of the system. These tests constitute a very high-grade specification document: because they are executable, they are perfectly formal and perfectly definitive, unlike typical text documents that are subject to misinterpretation. Automated tests either work or not: there is no need for interpretation.

Modern testing tools like Fit and Fitnesse allow tests and textual descriptions of requirements to be intermixed: these tests are Web pages that can contain any description desired. At any time, any reader can press a screen button and run the tests, getting an immediate determination of the extent to which the program meets its specification.

The design is treated similarly. The main place for the design to be is in the code. An Agile project is producing a number of “living documents”, the most important of which is the program itself, which is produced in a growing, fully integrated form, from the beginning of the project right on until the end. Working together, the team communicates design essentials through conversation supported by pictures and documents as needed.

Communicating Outside the Project

There is sometimes a perceived need to communicate specification or design information outside the team. During the project, this is harder to justify than one might imagine: anyone with important design oversight ought to be part of the team, part of the conversation, rather than at the end of a narrow-bandwidth paper or pseudo-paper channel. If it’s deemed necessary, however, then the team should be tasked to produce such documents. Producing them as a matter of course is wasteful.

At the end of the project, it is sometimes important to leave the program in a maintainable state. The artifact where maintainability is most important is the code: if it is not maintainable, no amount of other documentation will help.

Code written in an Agile fashion will be maintainable. Agile teams are, by definition, maintaining the code from the beginning of the project to the very end, and therefore perforce keep it maintainable. Various techniques such as refactoring are used to keep the code maintainable. It is easy to know whether the code is in fact maintainable because Agile teams work together, and therefore everyone knows what’s good and what’s not. In addition, Agile teams measure their productivity in features per unit time, and should the code be getting less maintainable, that will be reflected in a measured drop in productivity.

Given that we know the code is maintainable, we might still want some external documentation to serve as a road map to the whole program and perhaps to detail any particularly interesting or difficult aspects of the system. The team should be tasked with producing such materials. In so doing, they will draw upon the materials they already have, such as their current system diagrams that are hanging on the walls, and their current set of comprehensive system tests. They will refine these and polish them up, publishing them in whatever form is desired. Since the essential information is produced as a matter of course, as informal but highly communicative material, it’s a relatively simple matter to do that polishing. A prudent team will photograph, scan, or simply archive all its significant “cave paintings” as it goes, to serve as reminders for this final documenting task.

It might be argued that this documenting should be done along the way, as a matter of course. If one is sufficiently concerned that it won’t be done at the end, but that it will be of value, then of course it’s possible to work that way. However, such a practice is invariably wasteful, in two regards. First, most of the material will be of no value until the end of the project, and therefore producing it early is investment with late return. Second, by the nature of the Agile project, much of the base information will change, requiring rework on documents which are not being used. This is doubly wasteful.


In summary, the questions of where the “big picture” and “specifications” and “design” are kept are good ones. Agile projects by their nature require different answers to these questions than would be appropriate to a more plan-driven project. The specification serves different purposes on an Agile project and is documented primarily by tests. The big picture is communicated by continuous conversation and dynamic pictures and documents created as the team needs them. The design is embodied primarily in the program, and secondarily, again, by materials created as the team needs them.

There may also be a need for external documentation of big picture, specifications, or design. Caution should be used when a project is tasked to produce such materials: it may be evidence of a stakeholder who would be more closely involved, rather than at the end of a documentation tunnel. Given that materials do need to be created, they are simply project features, and should be scheduled and tracked like any other feature.

Posted on:

Written by: Ron Jeffries

Categorization: Classics

Recent Articles

Refactoring — Not on the backlog!

There has recently been a lot of noise on the lists, and questions at conferences, about putting refactoring “stories” on the backlog. This is invariably an inferior idea. Here’s why:


When our project begins, the code is clean. The field …

Build it right to build the right thing

You can’t build the right product if you can’t build the product right.

I tweeted that this morning, in response to a Twitter-vibe that was flitting around. I’d like to follow it up here with a bit more meat.

The …