Xp Has Written Documents

People seem to think that because we prefer person-to-person communication, that an XP project never writes anything down.

We're Extreme, not stupid! We document what needs documenting, in the most effective form we can find.

ChryslerComprehensiveCompensation production support people write every support event in a spiral notebook. Once in a while we go through the notebooks and look for commonality, to find things to improve.

We write our IterationPlan on the whiteboard, cross things off when they're done, and erase the plan when its time for a new one. For the only thing we need to know about past plans:

Tracker writes down the estimates and actuals for all the EngineeringTasks. Once in a while we go over them and adjust the LoadFactor.

We record the results of all AcceptanceTests on graphs that we keep posted prominently on our walls.

We produce status reports discussing Resources, Scope, Quality, and Time.

We write up the procedure to go through to build a new configuration, to push code to GemStone.

Where we can, we write things down executably. The process for doing a payroll requires many steps. Input has to be read in the order available. Errors have to be looked at and corrected. Pay has to be run. Special payrolls such as disability have to be run. Test cases are checked. Exports are run. Downstream jobs are run. Crossfoot balances are checked.

We don't write those on a piece of paper. We have a GUI where the customers select the next thing to be done, and run one or more steps when they are ready. The steps record what they did, and the entire collection of steps, times, and results are recorded in what we call a WorkPlan?.

We don't write down our class definitions in a document or a picture. The class definitions are written down in a specialized documentation language called Smalltalk. We don't have a document somewhere that tells us what the method named removeDeadEmployeesFromPopulation does. Anyone who wonders what it does, contact me by email.

We don't worry about why we remove dead employees either. We have a story, written down on a card, that describes what's going on and enough of the why to know.

We don't write down that you have to reload certain classes' class variables when you change certain methods. We write down UnitTests, in that specialized documentation language Smalltalk, that check to see whether the methods are newer than the variables, or that just reload things when necessary.

We don't write down how the system works. We know how the system works, and we have ten other people there who know it as well.

Would we do something differently if there were only two developers ten years from now? Of course, and we'd do it ten years from now. We wouldn't do anything differently today, because nothing we write today will be current ten years from now.

-- RonJeffries

Ron, I'm afraid to ask what removeDeadEmployeesFromPopulation does! It's easy to imagine what it would do in a payroll system. I'll be content to presume what I imagine for fear that I might learn otherwise! -- Kiel

Actually I'm working on some software for BuffyTheVampireSlayer?.

We don't write down our class definitions in a document or a picture. The class definitions are written down in a specialized documentation language called Smalltalk. ... We write down UnitTests, in that specialized documentation language Smalltalk, that check to see whether the methods are newer than the variables, or that just reload things when necessary

Sam, my customers don't want to know what my class definitions are. They want to know whether the system works, which they find out with AcceptanceTests. They sometimes want to know HOW it works, and we show them with CRC. It's fast, easy, they understand it, they can get involved. Much better than UML for dealing with real people.

Help me find where I'm insisting on Smalltalk being everything. Isn't most of this page about other forms of documentation? Are you possibly hearing something I haven't said?

If customers want any form of documentation whatsoever, even pictures, they just schedule it as a UserStory and we just estimate it and do it. What's described here is what we have wound up doing for over two years.

There is no "insistence on Smalltalk being everything". Personally, I use Java. ;->

But seriously, Sam, are you showing class definitions or specifics of API usage (in any form) to customers? Are you assuming that documenting class definitions in Smalltalk precludes providing end-user documentation when that is appropriate?

As for those customers who want to know how something works, very few in my experience had any real desire to understand; they just wanted evidence that I understood. I think diagrams tend to look like smoke and mirrors to such skeptical customers.

-- KielHodges