Extreme Documents

First, please refresh your memory of AlistairCockburn's observation AlmostExtremeProgramming. He makes a really great point, though we'll try to refine it here.

From Alistair's story, please hold in mind that XP requires that you have on-site customers, and all the developers very close together. Now let's look at what an Extreme project must document, and what it might document.

Requirements Documents

The customer's requirements must be documented in XP, in two forms. First of all, every single requirement that will be worked on must be written, by the customer, on a card: UserStory. Each UserStory is given a priority by the customers. They can change this at any time. Some UserStories are also given a risk rating, or a dependency rating, in a practice we call WorstThingsFirst.

UserStories are estimated by developers at the time of ReleasePlan. This estimate is written on the card. It is allowed, but not required, to keep the estimates in a spreadsheet or other document.

UserStories are doled out to the developers during IterationPlanning in the iteration where they are to be implemented. When completed, the customer gets the card back. They should keep it.

Finally, customer requirements are documented in another form. Every requirement is represented by one or more AcceptanceTests that determine whether the program meets the requirement. We would argue that these tests are in fact documentation of requirements with the added feature that they check to see if it's done. Developers use the tests proactively during development to find out whether they're done yet.

Design Documents

In an ExtremeProject is underway, design is done using the CRC method. The customers may be involved in this if there is a need to feel sure that the developers understand the UserStory. They may also be involved because they are interested.

After a CRC session, XP does not as a matter of course produce a document artifact. Instead, the developer immediately turns to the system and builds what has been designed. XP picks chunks of work that allow this to be done in a couple of days, not weeks or months, which makes it practical (we think sensible) not to build a temporary artifact such as a UML diagram to represent what will be built.

Code Documents

We comment methods only after doing everything possible to make the method not need a comment. We prefer to clarify the code directly over putting in an explanation of what the code could say it if were better done.

We recommend class comments, but observe that this recommendation is often not followed. On ChryslerComprehensiveCompensation we have detected no suffering due to lack of class comments. If and when we do detect suffering, we'll probably write UnitTests that check classes for non-trivial comments. Since team members are conscientious, they only need a reminder. It should not be necessary to check for quality of comment.

We have written "literate programs", cf DonKnuth, and no one has used them. Too bad, really, they were cool.

We have determined that code documentation is non redundant when written from a "how to use" instead of a "how it works" perspective. This is important to facilitate refactoring, since it is easier to read a comment header instead of analyzing a class or method to determine its purpose. This is especially true when everyone owns the code.

Low usability of traditional "literate tools" originates in the excessive formatting rules that the programmer must obey to produce a well-formatted document. Tools like this one (http://www.ptlogica.com/TwinText/overview.htm), encourage real world, "no overhead" documentation practices.

Reporting Documents

See FourVariables for a discussion of how we report resources, scope, quality, and time. PlanningGame, UnitTests, and AcceptanceTests are also relevant.

Customer-Required Documents

When the customer wants a document, such as a user manual or a nifty chart for their wall, they write a UserStory that asks for it, and they put it in an iteration. We sign up, estimate, do.

What about policy/procedure documentation? Are things like UserStory and PlanningGame, etc., which document various things about XP, actually shown to ExtremeNewbies? or is it all communicated face-to-face, or some combination thereof?

Face to face and situated. Remember that the practices are constantly evolving, much as the software is evolving, so keeping precise written descriptions of the practices would be counter-productive, so long as everyone has the same understanding of a practice. The pages here should be treated as a starting point. If there are problems, change something, measure the difference, and move on if the problem gets better.

Has anyone had any experience working in an XP project with specialized TechnicalWriters? On one hand, it is often mentioned that programmers are usually bad at writing manuals that users can understand, and it is preferable to hire professional writers. On the other hand, a writer writing documentation for an ExtremeProject is likely to have some difficulty gathering the information that needs to be documented, because a lot of stuff is written down only in code, UserStory or AcceptanceTests, and to collect all of this in a user-readable document must be quite hard. -- DmitryJemerov

One of the benefits of PairProgramming is that a newbie or a tech writer can pair up with experienced developers. There's no better way to learn about a system! UserStories can also form a great outline for user documentation -- RK

We are trying a WikiWiki for ExtremeDocuments. It gives everyone, customers and developers, ownership of the documentation and helps keep the documents a living, changing thing, just like the IncrementalDelivery cycles. Is anyone else doing this? -- JeffSandys

First, I don't pretend to know anything about ExtremeProgramming. However, I've worked on a documentation team that was very efficient and not at all traditional in the way that technical writers usually operate. Our keys to success were:

- Programmers must be able to explain things ONCE and only once, or they get upset. This means that your technical writers have to "get it" or record it. The tech writing lead should be a programmer, so he can explain things to the lower level tech writers again if necessary. The main programmers should not be distracted again if at all avoidable. Face it, most programmers see documentation people as the same sort of "necessary evil" as lawyers.

- The documentation should match the code in structure. That is, if the code is object oriented, the documentation should be object oriented as well. If an object changes, the user documentation related to that object should be localized, and easy to fix. If you have functional code, you should devise functional documentation (similar argument about knowing where to fix the docs when something changes in the code).

- In order to have talented technical writers, at least some of them must have been programmers in a previous life (if you have a very technical product) or be able to read code at the very least.

- Pay enough to get the best technical writer you can afford. You don't save money by hiring the low bid technical writer.

- Devise a method for SingleSourcingDocumentation. This is critical to avoiding redoing work within several different systems. --KellyAnderson

This page mirrored in ExtremeProgrammingRoadmap as of April 29, 2006