XProgramming
>
XP Magazine
>
Natural XP: Documentation
COLLECTED TOPICS: Adventures in C# |
Documentation in XP | Book Reviews
Natural XP: Documentation
10/07/2001
Contents:
On one of the mailing lists I frequent, I commented that if people required discipline or management pressure to do documentation, perhaps that was a sign that it would be better to find a way of communicating that people found more natural. Asked in reply whether I thought the XP practices were natural in that sense, I said:
Yes. At least the practices are trying to go with the natural instincts of people (and of programmers). They try to set up behaviors which are self-sustaining, not through discipline or through pressure, but because they have results which are good and which are proximate enough to the behaviors so as to reinforce them.
In subsequent discussion, some folks wanted to hear a bit about how XP tries to "go with the flow". Here are some thoughts on the subject. We'll look at how XP ensures that you have the communication you need, without increasing the documentation you have to write.
Documentation, or Communication?
It's a truism that programmers don't like to write documents. It's also a truism that on many projects the documents get out of date. It's conventional to blame the latter on the former, but the truth is that when the schedule gets tight, managers and project leaders are just as inclined to skip the updates as are programmers.
It's even possible -- this is just an idea, don't hold me to it -- that programmers don't like documentation because managers make it clear that what they really want is the program.
What do programmers like? They like to program. They like to write code; they like to make it work; they like to make it beautiful. How can we go with that natural instinct and meet our needs for documentation?
To begin with, let's look at why we want that documentation. For example, documents are used to communicate: to communicate requirements, internal design, status and information needed externally to the project. Let's look at those in turn. For each, we'll focus on what needs to be communicated and how XP helps make sure that the communication happens.
Communicating Requirements
Some projects work from large requirements documents specifying what needs to be in the product. There are some issues with the use of such documents, and sometimes they are quite important:
- Documents don't really communicate very well. Paragraphs and pages later, there is still important information missing.
- Documents aren't easy to write for customers. They require them to make their vague ideas of the product solid. There's value to this, of course, but risk as well. Writing a document makes vague ideas solid before there has been much effective feedback about the ideas. Many a bad idea has been cast in stone and implemented because it was in the requirements.
- Documents take time. I know of a team that essentially waits for three months while the requirements are hammered out for their next release. Oh, they get a little work done, but not much.
Requirements documents may sometimes be necessary, but they are not without cost. XP tries a more natural way to communicate requirements: conversation.
In XP, there is the notion of the "On-Site Customer". Someone who knows what is needed -- ideally the actual customer or user -- is near the team at all times. They communicate the requirements directly, through several of the XP practices.
Release Planning Communicates Requirements
During the release planning process, the Customer explains all the requirements stories. There is discussion with the programmers until they understand the stories well enough to estimate them. This is communicating requirements.
Iteration Planning Communicates Requirements
During the iteration planning process, the Customer explains all the stories in more detail: enough detail for the programmers to figure out the detailed tasks to implement them. This is communicating requirements
Acceptance Tests Communicate Requirements
The XP customer defines, and the team writes, acceptance tests for all the stories. These tests serve as executable requirements definitions. They can also be used quite readily as part of a tracking and documentation process showing that requirements have been implemented.
Informal Conversations Communicate Requirements
Because the Customer is On Site, she is also available for questions to clarify details of the requirements. She quickly learns to control how many interruptions she gets by improving the information she communicates during release and iteration planning. Too little, and she gets too many interruptions. Too much and she spends too much time in preparation. She can balance things between writing, conversation, and question answering to suit her own needs.
Natural Communication of Requirements
In summary, the On-Site Customer practice converts an inefficient paperwork exercise into a dynamic conversation discussing requirements as the project goes along. Everything is communicated -- must be communicated if the tests are to run -- and the balance between paper, presentation, conversation, and question answering can be adjusted to suit the participants.
Communicating Internal Design
All the members of the team need to understand the system. They need to be able to advance the code, to make it do whatever is needed. They need to do those changes in a way that are consistent with the overall shape of the code, and the direction it is moving: we might say with its design.
One way to be sure that everyone on the team understands and follows the design is to create a design and document it with UML diagrams or words or both. Everyone would agree that you shouldn't do too much of this up front, but it's hard to say how much is too much.
To communicate a design in this way, you need good-looking documents. It's all very well if two of us design on a bar napkin with a ball-point pen, but if it has to communicate with the whole team, we really will need to produce something better-looking and more comprehensive. Thus we need a word processor and a diagramming tool, and the time to use them to build the documents we need, and to maintain them, don't we?
Well, no. Watch your programmers. They're always jabbering about design, drawing pictures on those bar napkins or on the whiteboard. They're always drawing circles and arrows and a few words beside each one. They're always communicating about design -- it's what they do. How can we use this natural communication to support the bulk of our need for in-team communication, reducing the need for formal documents?
Release Planning Communicates Design
The XP release planning process includes a step where the programmers take the stories and discuss them among themselves, in order to estimate them. To estimate them, they figure out roughly how to implement each story. Guess what: the programmers are communicating about design. And watch them carefully: sometimes when they think they might forget, they write a note about how to implement a story, right on the card! They're recording enough about the design to remember it later. This is design, and communication of design.
Iteration Planning Communicates Design
The XP Iteration planning process includes a step where the programmers brainstorm the tasks to do each story, putting the tasks on the whiteboard for later signup. This is a design step. The whole team is participating in the design, and seeing it take shape. The key design components are left on the whiteboard until implemented. This is design, and communication of design.
Day to Day Development Communicates Design
In XP Installed, I describe the Quick Design Session: a few programmers get together and do a little CRC session or draw some UML or discuss how to do something. When they come up with something interesting, they tell the folks who weren't in the session about it. They do this naturally: it's interesting and they want to talk about it. If they come up with an important notion, they'll draw and write it on the whiteboard and leave it up while it's useful. This is design, and communication of design.
Pair Programming and Collective Ownership Communicates Design
XP teams practice pair programming. Pairs switch around daily, with everyone working with everyone. XP teams practice collective code ownership, so that everyone can (and does) work on all parts of the system from time to time. This is communication of design.
Refactoring Communicates Design
An essential aspect of XP is refactoring. Martin Fowler's book Refactoring is subtitled Improving the design of existing code. Refactoring is a process whereby the programmers (in pairs, of course) examine and consider whether the code is reflecting the design in their heads, and consider what the code is saying about what the design should be. Then they improve the code to improve the design. This is design, and communication of design.
Natural Communication of Design
Within the XP team, the practices bring about a high level of common understanding of the design. Using the natural willingness of programmers to talk about what they are doing and how cool it is, and using pair programming, XP teams spread what needs to be known without the need for much formality. Is there still a need for documentation within the team? Certainly there is, and each team and its management need to figure out what. But for internal purposes, there's not much.
Communicating Status
Some aspects of your status certainly need to be communicated externally to the project team. These communications will often -- but not always -- lead to documents. In the next section, Communicating Externally, we'll look at how to get those materials. Here, let's consider the information, and how we can be sure folks know what they need to know. We've already mentioned all the conversation that goes on on an XP project. This does a lot to communicate status. Here are a couple of additional general techniques to start us off.
Standup Meeting
XP recommends a daily "standup" meeting, where the team stands in a circle and quickly raises issues that people need to understand. This will include design issues and the like, but the main thing is a quick review of status, requests for help, problems encountered, and discoveries made. The standup meeting makes sure that all the attendees know about everything that's going on. Naturally, customers and managers are invited, and should attend.
On one XP project I coached, the team manager wrote all the external status reports, and almost never had to go to team members for information, because he got everything he needed to know as part of the standup meeting.
Big Visible Chart
Is there important status information that needs to be fresh in people's minds all the time? One good way to get that to happen is the Big Visible Chart. Here are some examples of useful charts:
- Story Chart. You need to know how you're doing on getting stories done. Consider a simple bar chart, the height showing the total number of stories, with the number currently completed filled in. This chart shows any growth in the requirements, and shows progress toward completion, at a glance. This could be all you need. Or, graph both number of stories and the estimated size of all stories. (You'll very likely be surprised, if you try this, to find that the first graph is close enough. But if not, use them both.)
- Story Wall. Some teams keep all the story cards up on a wall, arranged in iteration order: the planned order of implementation. When the customer changes her mind about the order, or about a story, the wall is rearranged. Stories that are done are marked, perhaps with a bright green diagonal line through the card.
- Iteration Wall. The plan and status for the current iteration should be visible to all, all the time. Some teams write the iteration plan on the whiteboard. Typically when a task or story is done, the team will mark it completed. A glance at the wall tells everyone what's up. Other teams fill the wall with the story and task cards, marking them complete as they get finished.
- Acceptance Tests. Acceptance tests on an XP project show how much is really done, done to the satisfaction of the client. The best teams treat stories as done or not done, depending on whether the acceptance tests run at 100 percent. The rest of us -- and I have fallen in this class -- sometimes accept less than 100 percent on the tests. We draw a chart showing the number of tests, and the number running correctly. This keeps us aware of how we're doing, and provides a quick basis for adjusting the team's attention. The best way is to go to and stay at 100 percent at all times, but this technique is a good one as well. See the article in Software Testing and Quality Engineering for more on this chart.
These charts are just examples. Is there something your team needs to have in mind all the time? Make a Big Visible Chart: it could be all you need.
Communicating Externally
You may need external documentation to support the product, either at the design level or for user documentation. There's no magic here: just write a story asking for the document, schedule the story, and write the document. The natural flow of the process supports getting the work done. As far as I know, there's no "natural" way to get external documents written, but since the need for them varies by project, I'm comfortable saying that the customer just asks for (and therefore gets) whatever external documents are needed. Here are some quick hints.
- Status Reports: Send management copies of your Big Visible Charts, tied together with a few paragraphs.
- Requirements Tracking: If you need requirements tracking, try associating stories with acceptances tests, and maybe include a little version infromation extracted from your code management software.
The details of what to document and how to produce the information are always unique to the project and its people. But the focus that XP would recommend is always this:
Communicate using the hottest medium you possibly can: from face-to-face conversation at a whiteboard down through phone conversation, through email, video or audio tape, down to paper or its online equivalent.
Find ways to have people's everyday activities embody communication. Find ways to have their everyday activities automatically generate the information that needs to be published. Find ways to extract information from development artifacts like source code.
Treat periodic or specialized documents as stories: use your existing planning mechanisms to get them done.
Conclusion
Extreme Programming tries to make things happen in ways that people find natural and pleasant. In the case of documentation, this is accomplished by recognizing that the point is communication, not simply documentation, then using the most effective forms of communication, and the most automatic forms, wherever possible.
As always, questions and comments are welcome, and may often result in an update to this article or in a new one.
References
Scott Ambler: Essay on Communication.
Martin Fowler: What's a Model For?
Ron Jeffries: Documentation in XP.