User Docs In Xp

How does user documentation get written in ExtremeProgramming projects? How do doc writers get informed of new features (I'm assuming StoryCards)? How do doc writers know how to document the final implementations and user interfactions? When does this occur in the cycle?

Extreme Programming is a minimal set of rules; you must add to it whatever else you need. In this case, user docs. Use common sense. Or, use a compatible known method.

My suggestion would be, assuming you have technical writers tasked with the user docs (as your paragraph implies), that they be present at Acceptance Tests, or review the written Acceptance Tests, to see what has been added, how it is used, and what the Customer sees in it.

In our case, the user docs were written by the developers in spare (non-pairing) moments.

It seems to me that agile processes grew up largely in custom development, rather than end-user software, and so it does not have clear ideas on the roles of the user-focussed professions (tech writer, graphic designer, UI designer, QA, expert user) in the process.

My last job was at a medium-sized, well known developer of high-end 3D animation software. We had JimHighsmith come in to train R+D on agile development. All the people listed above (writers, designers, QA, SMEs) wanted to know where we fit in the process, but we didn't hear any clear answers. On the other hand, I was extremely enthusiastic about agile methodology because it put the user at the center of the process, encouraged talking to the users, and opened up the developers and the development process.

Here's what I got out of my first attempt at writing user docs for an agile project:

Scrums are the best friend a tech writer ever had. I would argue they are essential for any project, and it is most essential that the writer attend. It's amazing how many things that need to be documented but weren't on a feature card come up in conversation at a scrum... one developer will ask another why they changed how an option worked. Me: "Wait, you changed how an option worked?" Them: "Oh, yeah, we should have told you about that!"
Similarly, the writer must be involved in the planning process (the creation and shuffling of feature cards). I want to know what's coming down the pike, besides needing to know what the heck you guys are going on about.
Explaining things to the writer should be a feature card with a time associated. The manager can't assume it'll "just happen" in the developers' spare time.
In our project, I spent each cycle documenting things that were finished last cycle. This might not be ideal, but it kept me from starting docs on things that later changed or were abandoned.
The project wiki is our friend. Please, Mr. Programmer, keep it up to date and explain how things are supposed to work, and what doesn't work yet. In an ideal world, writers, QA, and expert users would all get this information directly from the developers (and scrums help immensely with this), but sometimes it's really nice to just have it written down (in a lightweight manner, of course).
One final observation: the documentation pattern in a "classic" development model is to delay writing new documentation until the end of the project, when every single feature is finished (or at least given up on) at the same time, creating a bottleneck in documentation and testing. In the agile model, I documented each small chuck as it was finished and its user interface finalized. This meant a much less stressful and hectic schedule for me, and I was forced to fill my relatively empty days with improving all other aspects of the documentation, rather than just pulling my hair out trying to figure out obscure new features that don't really work.

-- MattChaput

I am not a technical writer, but being in a few not-well-documented projects, I agree with you totally. The scrums are very helpful not only for the techwriter to get the information, but they can also influence the software. In one of my projects some features were omitted since the writer said she can't explain them. She was also helpful in finding good metaphores.

The most interesting issue to me on this subject is how to automatically test the docs. I guess it is impossible in the current AI tachnology, but maybe something can be done. I'm playing with the idea of automatically checking the examples in the manual. What do you think?

-- Moddy Te'eni

I know it's not what you're thinking of, but there are some ideas about unit tests for docs in AssociateUserDocsWithSource.

For docs with "runnable" examples (such as for a programming language), it would be pretty cool to unit test the examples... for each example, include (possibly hidden) information about what the result is supposed to be, then at build time extract all examples, run them, and compare the results. -- mc

In XP, users don't get docs. They just read the unit tests and the code. They should be able figure it out from there.

And next time I try to operate the Gnu C compiler, I'll just read its source code! Great. Luckily it wasn't written in XP.

CategoryDocumentation