External Documentation And Extreme Programming

I suppose this is another ExtremeProgramming challenge or three.

Architectural documents:

An Xp project will be bringing in new programmers. There's information about the system as a whole that these new people need to know. I'll accept TheSourceCodeIsTheDesign, but I don't think the source code is the architecture. How does documenting the architecture fit into Xp? -- PaulChisholm (who guesses it might fit in the same way in all methods: on the side, maybe necessary, often desirable, but not an integral part of moving from requirements to finished software)

RonJeffries explained ChryslerComprehensiveCompensation's architecture to me in about fifteen minutes with a set of blank cards. I suspect I could still recite it back. I remember reading someplace that KentBeck had said (how's that for a reach, correct me if I'm wrong Kent) if you can't explain a system using three or four objects, you don't have an architecture. C3 has Lines, Stations, Bins, and Parts (see LinesStationsBinsParts). The architecture sounded very reasonable to me. I'm sure I don't know enough of what it takes to start working with that system from those fifteen minutes, but if I was a newcomer, I'd be paired with someone just like everyone else, and given the fact that the pairs constantly switch, anyone would be able to tell me practically anything and I'd learn the system over time. Pretty elegant, eh? -- MichaelFeathers

Is there some principle of ExtremeArchitecture?? -- PaulChisholm

End-user documentation:

A lot of traditional methods call for up-front documentation that can be used by designers, developers, testers, and (my main point here) tech writers. This implies the end-user documentation can be written (at least started) before the software is completed. (In practice, the up-front documentation may bear no resemblance to the finished software, but at least these methods address the problem in an ideal world.)

With Xp, the only up-front documentation is UserStories. Are these kept? Are they kept up-to-date? Are they sufficient for writing end-user documentation?

-- PaulChisholm

They're kept, I'm not sure why. Mostly to hold up the done stack and not-done stack and show how far along we are. Really.

Don't use up-front documentation to write end-user documentation. Instead, have the tech writers there with the clients and programmers from the beginning gaining an understanding of the requirements alongside the programmers.

We don't have any end-user documentation. The users worked with us until they knew how to use the system. Obviously not all projects could do that. When we need documentation, we schedule it like a story, and someone signs up and writes it. We could use dedicated writers, I spose, if the docs had to be that cool. But we haven't, yet.

(Note: the most productive programming effort JimCoplien ever observed, the Quattro Pro for Windows 1.0 project, had dedicated writers producing even the internal documentation. -- PaulChisholm)

As I understand how C3 did it, the UserStories are not kept up to date in any meaningful sense (although new stories may be written). And they aren't sufficient for writing documentation or even software, at least not as static self-contained things. XP insists on most communication taking place face to face and interactively, not in written documents. That is how the programmers gain a real understanding of the requirements. (Am I on target, C3?) -- KielHodges Absolutely, Kiel!

Makes perfect sense, for C3. (I guess any new users will learn from the existing users?) But I've got a tech writer who's put together a 180 page User's Guide. Mostly he's working from specs (at least in theory). Can you describe how, in an Xp project, he would have collected the information that went into the book? -- PaulChisholm

Pop Quiz! Take out a blue book! Knowing the XP methodology as well as you do, how might a tech writer become familiar enough with the requirements to write a book about them? -- RonJeffries

Sort-of end-user documentation:

Say the product of an Xp project was a library, or an API, or some such. Presume, just to make things hard (and to distill the essence of the problem at hand), the library was not distributed in source form. Do you know how, in an Xp project, you might keep the interface in the code in sync with some written description of the interface? -- Paul Chisholm

While it's not part of XP, LocalityOfReferenceDocumentation discusses this --BradAppleton

We wouldn't keep the interface in the code in sync with the description. The code is master, not slave: we would keep the description in sync with the code. How would we do that? Perhaps we'd machine-generate the document from the code. -- RonJeffries

I'm hip to the above! There's a product called Genitor that can do this for C++ (see http://www.genitor.com/). In fact, Genitor does a lot of other nifty things that make it about as close as Ive seen to a C++ code-creating environment that does lots of VisualWorks-ish things for you. -- BradAppleton

A kind Xp person explained how the C3 project got from paychecks to LinesStationsBinsParts. I thought this was an interesting story. It also explain how they got from the simplest thing that could possibly pay somebody to what sounds like a manufacturing production line. Apparently the simplest thing is not always the obvious thing. -- Bob Haugen

CategoryDocumentation