Extreme Support Documentation

I understand that one of the major goals of XP is to avoid creating needless documentation. However, I think I may have a situation where documentation is definitely called for.

Assume you are a software developer in an XP shop. Assume further that "production" support of the software is done by an outside group (read "help desk"). If the help desk (first level support in our organization) is to provide any meaningful support to customers, then the staff will need more extensive documentation than just the source code.

What forms of documentation would you give to these individuals? A support manual? Would this consist of a set of user stories? In our environment, the help desk is usually called when "bad things" happen (disk crash, network connectivity loss, etc.). Admittedly, we are not an XP shop, (but we play one on TV :). I am curious as to how this sort of support would be done.

Would one of the help desk personnel be part of the development team, like the on-site customer?

-- DavidHurt

One way to look at this is to figure that DocumentationIsCode and let the developers write most of it. Specifically, they would write each UserStory as a section of the manual, and turn it over to a specialized doc engineer (if you have such a luxury). The doc guy would then pretty it up, and you would have a book that told you how to do just about everything the system was built to do.

--RobMandeville

Yes, but did anyone keep the entire history of story cards? How have newer stories modified older stories? It seems to me that if documentation is needed, it should be evolving with the software. See AgileRequirementsDocumentation.

-- Steve Jorgensen

My impression is, that the creation of the documentation should be driven by the same mechanism as the creation of code. The customer in this case are the people calling the help-desk. Only such documentation as needed to aswer the questions should be placed in the documentation. This is of course difficult, if you do not already have customers. But in the usual case, you could invite some few customers (possibly those, that call repeatedly) and capture their questions. The same mechanism could be used for online-help. I think, that FAQs are the usual self-organized form of this process at work.

-- GunnarZarncke

I believe it is not the "customer" that calls the help desk, it is the "user" who works for the customer, and that person cannot be counted on to call for help when they need it or tell you when they've wasted time that could have been saved with better documentation. I believe that the nature of the necessary documentation and online help should be determined in usability testing.

Situations that don't call for usability testing probably don't call for user documentation or online help, so I think that should cover it. If comprehensive documentation or online help is required, I think it's important to make sure it stays in sync with the product, and to have automated assistance to detect when synchronization is broken.

-- SteveJorgensen