File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Agile and Other Processes and the fly likes Iterative user documentation -- madness for tech writers? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Iterative user documentation -- madness for tech writers?" Watch "Iterative user documentation -- madness for tech writers?" New topic
Author

Iterative user documentation -- madness for tech writers?

Hedley Finger
Greenhorn

Joined: Sep 20, 2007
Posts: 12
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?
Frank Carver
Sheriff

Joined: Jan 07, 1999
Posts: 6920
I did see an interesting article on this topic


Read about me at frankcarver.me ~ Raspberry Alpha Omega ~ Frank's Punchbarrel Blog
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
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.


Author of Test Driven (2007) and Effective Unit Testing (2013) [Blog] [HowToAskQuestionsOnJavaRanch]
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Iterative user documentation -- madness for tech writers?