This week's book giveaway is in the Reactive Progamming forum.
We're giving away four copies of Reactive Streams in Java: Concurrency with RxJava, Reactor, and Akka Streams and have Adam Davis on-line!
See this thread for details.
Win a copy of Reactive Streams in Java: Concurrency with RxJava, Reactor, and Akka Streams this week in the Reactive Progamming forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Junilu Lacar
  • Jeanne Boyarsky
  • Bear Bibeault
Sheriffs:
  • Knute Snortum
  • Tim Cooke
  • Devaka Cooray
Saloon Keepers:
  • Ron McLeod
  • Stephan van Hulst
  • Tim Moores
  • Tim Holloway
  • Carey Brown
Bartenders:
  • Piet Souris
  • Frits Walraven
  • Ganesh Patekar

Iterative user documentation -- madness for tech writers?

 
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?

 
author
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
 
author
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.
 
The world's cheapest jedi mind trick: "Aw c'mon, why not read this tiny ad?"
Java file APIs (DOC, XLS, PDF, and many more)
https://products.aspose.com/total/java
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!