Essential XP: Documentation

“Outside of a dog, a book is man’s best friend. Inside of a dog, it’s too dark to read.” –Groucho Marx

Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else.Trust yourselves to know the difference.

XP is designed to use face to face human communication in place of written documentation wherever possible. Effective conversation is faster and more effective than written documentation. When you bring people together, they need less paperwork.

Documenting Requirements

XP in its pure form has a customer (a business decision maker who knows what is needed and can decide priorities) who is “on site” with the team. We might argue about how difficult it is to get an on-site customer, but it doesn’t change the fact that when you’re in the room with people, you need not write them quite so many memos.

XP uses verbal discussion to explain to the programmers what is wanted. As we have said since the C3 project back in the late 90′s, those discussions are commonly backed up with tables of values, spreadsheets, even extracts from requirements documents coming from somewhere outside the project. As we say in Extreme Programming Installed, page 28:

User stories are made up of two components. The written card is the first. We recommend writing the story in just a couple of sentences on a card and pointing to any supporting documentation. The second component, and by far the most important, is the series of conversations that will take place between the customer and the programmers over the life of the story. 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.)

Most importantly, as we see above, the requirements are documented in a form that is much more definitive than a mere requirements document: they are documented in the form of automated tests that verify the results of using the software.

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

Some projects have a need to communicate requirements outside the team. This need is not addressed in the XP process. We’re not against it … it’s just not something we have spoken about, except to say this::

If there is a business need for a document, the customer should request the document in the same way that she would request a feature: with a story card. The team will estimate the cost of the document, and the customer may schedule it in any iteration she wishes.

Documenting Design

Like many other incremental methods reaching back as far as Boehm’s Spiral Method, XP grows the design rather than synthesizing it. Again, because in XP the programmers are all together, there is little need to pass much paper back and forth. The system is built in two-week iterations, and features are typically built in a matter of days (because features are broken down to be tiny, not necessarily because XPers are notably smarter than anyone else).

In such an environment, design artifacts are typically ephemeral. The team may draw some UML on a whiteboard or a tablet, then sit down to build the feature.

It is common for XP teams to have some pictures of the system’s design on the wall for extended periods. I observe that these seem to serve more as decoration than as documentation: people don’t look at them very often. They ask each other, or they pair program with someone who knows the answer. Why do they do this instead of look at the pictures on the wall? I believe it’s because verbal communication and pair programming work better. But I have no proof — only experience.

XPers teach that if the team needs a document, be it a drawing, a table, or words in a row, they should produce the document. We also teach that if you produce a document and don’t use it, that might well be a hint that you didn’t need it after all.

Again, this is inside the team. If there is a need to communicate outside the team, and it can’t be done by coming together, then of course it is just fine to write something. That just makes good sense. We’re Extreme, not stupid.

When it is time to hand off the software, whether to maintenance people or to users (perhaps programmers who will use the software to build other things, or other kinds of end users), then of course you need to build appropriate documentation to go with it. In the case of users, I’d think this would be just like any other kind of user documentation. In the case of maintenance programmers, we typically suggest a short document describing the system’s architecture or metaphor (perhaps with some UML diagrams), the key concepts, the important classes, and so on. This should, we suggest, be thought of as an introduction to the system, a high-level index if you will.

Documenting Code

XP has very high focus on incremental development. The development cycle is to begin with Simple Design, communicated through Pair Programming, supported by extensive Unit Tests, and evolved through Refactoring.

For this to work, it must be possible to refactor the code: the code must be very clean and very clear. There are rules (see elsewhere a discussion of the rules of simplicity relating to reusability) that help programmers produce clear code. In essence, if there is an idea in our head when we write the code, we require ourselves to express that idea directly in the code.

We treat the need for comments as “code smells” suggesting that the code needs improvement, because it isn’t clear enough to stand alone. Our first action is to improve the code to be more clear. Whatever we cannot make clear in code, we then comment.

Unit tests are also documentation. The unit tests show how to create the objects, how to exercise the objects, and what the objects will do. This documentation, like the acceptance tests belonging to the customer, has the advantage that it is executable. The tests don’t say what we think the code does: they show what the code actually does.

Inside the team, this is typically enough code documentation. Outside the team, similarly to the sections above, you might need more. Again this would be most likely at some time when the code is to be transmitted to someone else. At that time, if a document is needed, we suggest that it should be written.

Manuals

The best way to do manuals is probably to have the writers work right alongside the programmers, as part of the team. For a lighthearted look at that idea, please see Manuals in Extreme Programming.

Other Documentation

As XP is intentionally a minimal methodology, we do not follow the RUP path (an honorable path, just a different one) of listing all the documents you might want, from which you select those you deem suitable. Instead, XP puts the people who are stakeholders in the project together, in an environment of rapid feedback, and trusts them to work out what additinal things they need … not just documents but any other form of project enhancements.

Some people argue that this is risky, that teams “can’t be trusted” to figure out what’s needed. We find that in fact teams that set up rapid feedback cycles learn quickly and do just fine.

Conclusion

I have covered the main documentation areas that came to mind. I think it should be clear that we desire strongly to minimize documentation, but that just like most everyone, we want all the documentation that the project actually needs, and no more. If there is a difference in focus, it is that we believe that with close person-to-person communication, the team will quickly find out what is needed. Therefore we specify a safe minimum of process — including documentation — rather than piling things on just to be sure.

If you have questions about specific documents and when we’d recommend them, email me, or post a question on the extremeprogramming group on yahoo. We might even get a followup article out of the deal.

Posted on:

Written by: Ron Jeffries

Categorization: Articles, Classics

Recent Articles

XProgNew – Working with layout

I’ve been trying to learn some things about how the new implementation will handle the front page. The front page has a top row the most recent articles in two categories, “Beyond Agile” and “The Annals of Kate Oneal”, and …

XProgNew – today’s problem

With Bill Tozier, I’m working on re-basing XProgramming.com from WordPress to Ruby/Sinatra etc. We tweeted a bit about an issue we ran into today. It goes like this:

The image we had of the new site is that each article …