Requirements Documentation

Requirements documentation in XP is not necessarily that different from traditional requirements documentation. A lot depends, however, on how you interpret XP s teachings in this regard, because so much of this area is optional. The basic message appears to be (to sum up the 20 XP books and various Extremo Web sites): Do as much or as little requirements documentation as you feel is necessary, but personally we do as little as we can.

It s worth briefly comparing XP requirements ( user stories and so forth) with requirements documentation in non-XP projects.

Requirements Documentation in XP Projects

HYPE!  

We combine a focus on verbal communication with automated tests to communicate requirements. The result is much lower need for written requirements within the team. ^[3]

In XP, the requirements are captured as one- or two- sentence user stories ( handwritten on story cards), resulting from conversations with the customer. The user stories are promises for future conversations (i.e., they are only the first step in a two-step process). These future conversations take place during the iteration in which the user story will be implemented.

Additional documentation can also be attached to each user story to describe the requirements in more detail. If the customer requires extra documentation, it must first be written, scheduled, and tasked as a user story.

An XPer who posted a message to the Software Reality XP forum made this comment about requirements in XP:

Most XP teams do have some written requirements, and they are usually fairly detailed. What they typically are not is: comprehensive, formal, subject to change control procedures. ^[4]

If you re an XP customer, this should worry you. You can, of course, request more permanent documentation (via the magic of stories), and request that it be put through change control. But (and this is a big but), you have to know that you need to ask for this explicitly. You might be used to other projects in which requirements documents (and reviewable design documents) just sort of happened . When you re working with an XP project, somebody might tell you, but then again they might not, because the XPer mind-set is to produce only the documentation that is asked for.

Requirements Documentation in Non-XP Projects

Requirements in non-XP projects ( certainly the projects we ve worked on) tend to be documented as bulletproof specifications, with numbered requirements describing what the system is intended to achieve from the customer s point of view.

We compare requirements with user stories in Chapter 10.

 

Producing such a specification usually involves some in-depth analysis of the problem that drives each requirement and, in turn , the root cause behind each problem.

To produce a specification this detailed for an entire project takes a lot of effort, but it s worth it because many problems that would not have been discovered until later when a lot of code had been written are identified and highlighted early on.

To get around the waterfall ^[5] effect (where the programmers are waiting around for months on end for the requirements to be completed), some initial analysis is carried out that divides the project into smaller, logical subsystems. Requirements for each of these subsystems can then be fleshed out in more detail and in parallel.

If a particular subsystem isn t scheduled to begin for a long time (e.g., an entire year), then detailed requirements analysis for that subsystem may also be pushed back closer to the time. This makes sense, because the requirements might change in the meantime.

Did Oral Documentation Kill C3?

As we mentioned in Chapter 2, a major contributing factor to the demise of the C3 project was the fact that the on-site customer (the goal donor) was headed in a different direction goal-wise from the project sponsor (the gold owner).

The normal method of getting around this fundamental problem is to write the requirements down in a specification. ( Anyone remember specifications? We have to confess, it feels just a little eerie having to write this paragraph. Countless systems have been built using specifications. Really!) The specification is then agreed upon and signed off by all those people involved in the project who could be considered to be a customer (i.e., the project stakeholders). This would definitely include the project sponsor.

The written specification is signed off in anticipation, before the next iterationbegins, so that there are no outstanding disagreements (e.g., between a local goal donor and a remote gold owner) on what goes in.

SOLUTION  

This sign-off procedure reduces the on-site customer s role from ad hoc specifier of new requirements to a less demanding role. In this role, the on-site customer (or the team of on-site customers) is simply there to clarify issues, clear up any confusion surrounding the requirements, and provide early feedback on the software produced during and at the end of each iteration.

If the customer does identify a need to change the requirements, a process of change and sign-off with the project sponsor should be followed. Then there is no confusion, just a single, unambiguous state at any time.

The trick is to have a process of change and sign-off that doesn t impact the project timeline (i.e., try not to put change control on the critical path ). Of course, this is where an effective project manager comes in, to handle whatever paperwork arises. This process shouldn t delay the programmers in any way.

XP gets you halfway to this process with its use of two-line user stories written on pieces of cardboard, but it lets the side down by recommending that these simply be incomplete, transitory artifacts ”promises of future conversations with the customer. Requirements need to be more complete than that. They need to show, before the next coding iteration begins, such things as expected behavior of the system, what the system should do when things go wrong or something unexpected happens, and architectural extremes (the maximum number of users, the maximum number of transactions per minute, and so on) ”basic things like that.

 

Design Documentation

Design documentation in XP is more controversial even than requirements documentation in XP. In fact, the rest of this chapter mainly covers design documentation.

It s worth emphasizing that some XPers do create UML models, and they do sketch designs on whiteboards , sometimes before coding. However (as we discuss in the next couple of chapters), the XP design process is based around the concept of evolutionary design ”that is, the up-front design phase is virtually nonexistent.

Design documentation in XP is also very ad hoc. XP has no guidelines on specifically what types of documents are worth producing and maintaining. The decision is left to the whim of the collective team ”whatever it thinks is best. Having said that, XP teams do pride themselves on readable code (including coherent , simple, clean object names and relationships), the intention being that the code itself is a design document. ^[6] XP has been supplemented by third parties (most notably Scott Ambler with Agile Modeling ) who provide better guidelines on what to document and maintain in an XP project.

See Chapter 15 for more about supplementing XP with better documentation and modeling techniques.

 

Documenting for the Future

Extremo author Martin Fowler has this to say on UML and XP:

There are a number of points of incompatibility . Certainly XP de-emphasizes diagrams to a great extent. Although the official position is along the lines of ˜use them if they are useful, there is a strong subtext of ˜real XPers don t do diagrams. This is reinforced by the fact that people like Kent [Beck] aren t at all comfortable with diagrams. Indeed, I ve never seen Kent voluntarily draw a software diagram in any fixed notation. ^[7]

Perhaps Kent Beck is averse to diagrams because he has stated on the C2 Wiki that visualizing objects before coding is a dangerous practice and should be stopped (it s a Zen thing). ^[8]

More about Zen and the Art of Software Maintenance in Chapter 16.

 

Fowler s quote highlights the fact that design documents in XP are mostly transitory. This contrasts greatly with the notion of design documents in, say, RUP, which calls items of documentation artifacts (which suggests documents that are long-lived and may be dug up several years later). Although this notion may at first seem absurd, the maintenance teams who actually do need to dig up that documentation several years later will offer a prayer of thanks to the previous team members for their forward thinking.

This approach is crystallized by two of the Agile Modeling core principles:

• Software is your primary goal.

• Enabling the next effort is your secondary goal.

  Your project can still be considered a failure even when your team delivers a working system to your users ”part of fulfilling the needs of your project stakeholders is to ensure that your system is robust enough so that it can be extended over time. ^[9]

Of course, not having a documented design is often regarded by programmers as good job security. If you re an XP customer or manager, take note!

The following quote is from Ron Jeffries on good old comp.software.extreme-programming:

GROUCHO  

Customer says ˜Please do these eleven things . Team says ˜We can do any ten this iteration, which ten do you want first? .

Customer says ˜I want eleven . Team says ˜We can do any ten this iteration, which ten do you want first? .

Customer says ˜You are idiots, I need eleven . Team says ˜Yes, we are, but we can do any ten this iteration, which ten do you want first?

Customer says, ˜If you won t do [eleven], I ll get another team . Team says, ˜If you can get a team that knows the system as well as we do, costs as little as we do, and that can do eleven, you should definitely get them. While you work on that, we can do any ten this iteration. Which ten do you want first? ^[10]

What really got to us about this hypothetical conversation (aside from the fact that it stereotypes the customer as an unthinking moron) was the attitude barely hidden behind it. There is an implied So bite me! at the end of the team s response. It sums up the XP attitude that the customer can t afford to get rid of the XP team because no one else knows the system as well as [they] do.

Why doesn t anyone else know the system as well as they do? Because there s no frickin documentation! Therefore, the XP team calls the shots. The inmates are running the asylum (again ^[11] ). The team is on the snack -laden comfort train all the way to Smugville, at least until its project gets cancelled.

The Code Is the Design!

On XProgramming .com, Ron Jeffries writes this regarding design documentation (as driven by user stories):

GROUCHO  

Those conversations will be captured as additional documentation that will be attached to the card, will be acted out during Class Responsibility Collaborator (CRC) design sessions, and, better yet, as acceptance tests and application code. (Emphasis mine.) ^[12]

So that s official, then: Although the design is acted out during CRC design sessions, it is documented as application code. Going by Ron s description, acceptance tests are a murky halfway house between requirements and design.

Because the acceptance tests are modeling the requirements as source code (or scripted code, which from the customer s point of view is essentially the same thing ”see Chapter 5), they blur the distinction between requirements and design. This wouldn t be such a bad thing if XP provided a clear route to get from user stories to source code. ^[13] Unfortunately, this gigantic leap is left as an exercise for the reader. This leap isn t made any easier by the fact that it s now less clear exactly what is a requirement versus what is design ”because the distinction between them has been blurred.

VoXP
Voice of eXPerience: Pairing Replaces Documentation

This account was sent to us by an XPer who wishes to remain anonymous.

A tenet of XP is that documentation (such as design diagrams and detailed comments in the code) is unnecessary because since everyone works on all the code, chances are one member of the pair will have worked on any piece of code and will therefore understand it without documentation.

I believe that this lack of documentation is a serious flaw of XP that will affect all except the smallest teams on the shortest projects. The fact is that everyone doesn t work on all the code. If you ve got eight on a team ”four pairs ”you get to see a fraction of the code as it s written. Sure, you ll modify some code and debug through some more, but I think it s fair to say that if the code is well written and works, each team member will never see much of the code. If the project continues over the years, people will leave and new people will join, and the situation will get worse .

Even if you ve written the code yourself, it doesn t mean you remember it. I ve had to relearn code I wrote months or years before.

My experience suggests that some basic documentation is necessary, and pairing in no way reduces the need for documentation of code and design.

 

^[3] Ron Jeffries, Essential XP: Documentation, http://www.xprogramming.com/xpmag/expDocumentationInXP.htm, November 21, 2001.

^[4] Keith Braithwaite posting to http://www.softwarereality.com/lifecycle/xp/forum.jsp, February 8, 2003.

^[5] The waterfall model was formalized in 1970 in a paper by Winston W. Royce called Managing the Development of Large Software Systems: Concepts and Techniques. Although Royce didn t actually use the word waterfall in this paper (and he certainly wasn t describing the rigid, failure-prone process of A flows into B flows into C, no exceptions that most people associate with the term waterfall ), he is nevertheless generally attributed as the inventor of the waterfall model.

^[6] However, we have argued elsewhere that the code is the design is not a sufficient replacement for design documentation, because proper design documentation is at a higher level of abstraction to the code.

^[7] Giancarlo Succi, Michele Marchesi, et al., Extreme Programming Examined (New York, NY: Addison-Wesley, 2001), Chapter 1, Is Design Dead? (written by Martin Fowler). (See also http://www.martinfowler.com/articles/designDead.html.)

^[8] See http://c2.com/cgi-bin/wiki?ToAyoungExtremist .

^[9] Scott Ambler, Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process (New York, NY: John Wiley & Sons, 2002), p. 28.

^[10] Ron Jeffries posting to the newsgroup comp.software.extreme-programming, subject: Managing Scope, January 30, 2003.

^[11] See the section Big Words Like Constantinople and TerminationCanBeSuccess in Chapter 4. We also discuss Alan Cooper s The Inmates Are Running the Asylum in Chapter 15.

^[12] Ron Jeffries, Essential XP: Documentation, op. cit.

^[13] Modern development methodologies typically suffer from a crucial missing link between analysis and design ”that is, a predictable way of getting from requirements to source code. There is also a common misconception that there is no reliable way of achieving this via a logical process (so why bother trying), as we discuss in Chapter 8.