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:

-- 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.

See also WriteTheUserManualFirst, AgileForNonProgrammers, LocalityOfReferenceDocumentation, AssociateUserDocsWithSource

View edit of April 11, 2013 or FindPage with title or text search