• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Iterative user documentation -- madness for tech writers?

 
Hedley Finger
Greenhorn
Posts: 12
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This message originally appeared in the 'Pair programming sucks' thread.

I have posted it here as a completely new topic as it is my experience that discussions of XP/Agile development never include that other important development activity -- producing user documentation. Read on ...


Can anyone comment on the effect of XP/Agile development on the technical writers producing the user procedural and reference documentation? A programmer pair can make changes in an hour or so that takes the technical writer days or weeks to update in the documentation source.

This typically involves taking new screen shots, updating the reference material supporting those shots, adding new procedures, rewriting, moving content from one chapter to another, etc. Most documentation applications (Word, FrameMaker, etc.) produce binary files which cannot be merged so when major restructuring is required, one writer has to check out and own all the source and destination files to make the changes.

This situation is somewhat eased by using XML-based content management systemts for the doco source, which allow diffing and merging like code, but are not the complete answer.

Most discussion of XP/Agile focusses on developing functionality. But, hey, the on-line help, web interactive help and FAQs, and printed documentation are part of the product too! Do XP projects find themselves moving the release date because too many iterations mean that unfinished documentation is holding up release?
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Without being one myself, I suspect that being an Agile tech writer will be much easier when using tools that don't stand in the way of an iterative approach to documentation. I'd probably rather use LaTeX than word, for example.

A very nice experience report can be found at http://xprogramming.com/xpmag/Ferlazzo.htm
 
Lasse Koskela
author
Sheriff
Posts: 11962
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I've also consulted a smallish (< 100 people) company with their transition to agile methods where one of the most excited individuals was a technical writer.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic