wood burning stoves 2.0*
The moose likes Agile and Other Processes and the fly likes user documentation 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 "user documentation" Watch "user documentation" New topic
Author

user documentation

Zsuzsa Nagy
Greenhorn

Joined: Sep 08, 2006
Posts: 3
Hi!
I found quite a lot of information (for example by Scott Ambler) about the role/use of documentation in Agile but it seems to me that most of it is about "project documentation": plans, architecture documents, etc., not the documents that would go to the users of the product developed in Agile.

How do you work with the technical writers? Can you tell me about your experiences and impressions about how the development of the user documentation (User's Guide, help, or even API documentation...) is different from the process-centric development?

You guessed right, I'm a writer, not a developer :-)

Thanks in advance for your help!
Zsuzsa
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Hi, welcome to the ranch!

Unlike most agile teams we write use cases, which provide the bulk of the input for the authors. We plan, implement and deploy stories, but update the use cases as we go. The user documentation for our system is written by the people who supervise the people who use it. For the most part, we don't even see it. That sounds weird, doesn't it?

Is your user doc author the same customer who is in the story conversations? That person sounds like the best resource to explain how the system fits with the business process. Acceptance tests should have the nitty gritty details, like password must be between 6 and 8 character, must include at least one digit, is not case sensitive.

Stories would provide fragmentary inputs to the doc author, potentially out of sequence. That ought to make it challenging enough.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
We have one part time technical writer on the team. She attends the daily stand up meetings, participates in usability discussions and reviews screen texts and the like.

When we finished a feature, we put a short notice into a release notes tool we wrote. The technical writer than rewrites that to a customer-friendly release note (the output is something like the Eclipse New and Noteworthy document) and updates the documentation. For simple features she does that for herself, if she needs help, she simply pairs with one of the developers.

Seems to work fairly well, though I guess it could be improved.

See also http://www.xprogramming.com/xpmag/manualsInXp.htm and http://www.xprogramming.com/xpmag/Ferlazzo.htm for some more stuff on the topic.

Does that help?


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
Ernest Friedman-Hill
author and iconoclast
Marshal

Joined: Jul 08, 2003
Posts: 24183
    
  34

One thing we do on several projects is TDD (Test-Directed Documentation)

All our documentation is written in XML, which is used to generate HTML and/or PDF documents. We then have application tests that probe the application and documentation and make sure that every documented menu item actually exists, and every menu item is documented. For projects that embed a command language (and for us, that's most things) we do the same with the command language.

This doesn't help you write the documentation, per se, but it does tell you where the documentation needs to be updated. On a rapidly evolving project, this is a real help. For the Jess rule engine, which embeds a programming language with a couple hundred functions) this is a huge help.


[Jess in Action][AskingGoodQuestions]
Zsuzsa Nagy
Greenhorn

Joined: Sep 08, 2006
Posts: 3
Hi!

Thanks a lot for all the bits of info!

TDD sounds exciting, although the bulk of the product I work on now is a platform product with background processes and therefore with loads of architecture documents might not be the best candidate for the TDD you describe...

Thanks also for the links, I haven't thought about checking out XP. :-)

My gut-level feeling, before posting, was that the writer or at least the writing (if done by the developers) must be integrated to the development team. At the moment we have the writing team as a completely different unit, some writers are even off-site, and guess what: it doesn't seem to be doing good to the documentation... It was good to hear that at least some of you have the writers on the team. I hope to be able to persuade the bosses that we need to include the writers in the scrums, they should work in daily contact with the developers and architects, etc.

Thanks again for your help!

Zsuzsa
Scott Ambler
author
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
I think that people with tech writing experience should be included on the team because it's an important skill which every IT person should have. But, that doesn't mean that this person will only do tech writing. They should be prepared to roll up their sleeves and be actively involved in modeling, testing, programming, ... just like any other team member.

Also, you'll find that user documentation is typically written one iteration behind the functionality -- you want to wait until a feature has stabilized before you write about it.

- Scott


<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Scott Ambler:
I think that people with tech writing experience should be included on the team because it's an important skill which every IT person should have. But, that doesn't mean that this person will only do tech writing. They should be prepared to roll up their sleeves and be actively involved in modeling, testing, programming, ... just like any other team member.


Yes, I second that. Our tech writer, for example, is really good at noticing inconsistencies in the usability of our system...


Also, you'll find that user documentation is typically written one iteration behind the functionality -- you want to wait until a feature has stabilized before you write about it.


Unless you are brave enough to do what Ferlazzo did as reported in the second link I provided...
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Ilja, do you find the story to user doc granularity or fit is off some times? We may get a story that affects several use cases and user doc scenarios, or a whole series of stories that affect the same doc iteration after iteration. It can be kind of rough on the doc maintenance folks.

I'm reminded that before I was schooled in any kind of methodology (read the acronym CMM in a magazine but that's about it) my own method was to write the user manual first. I wrote a round-trip screen generator - text pictures to runnable prototypes to mainframe assembler code and back - so I could easily keep the doc and the app in sync over time. I thought I was darned slick. But thinking back, I believe customers never wrote or read the doc thoroughly enough to not have more ideas when they got the system. Surprised?
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Stan James:
Ilja, do you find the story to user doc granularity or fit is off some times? We may get a story that affects several use cases and user doc scenarios, or a whole series of stories that affect the same doc iteration after iteration. It can be kind of rough on the doc maintenance folks.


We actually recently finished a set of features for which we aggregated the user stories over months and only submitted them to our tech writer in one big batch. As far as I can tell, she wasn't realy very amused and would have liked to get them in smaller batches.

And frankly, I don't see why, with the right tools, you shouldn't be able to work on user documentation as incrementally and iteratively as on code...
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I went back and read that link you provided to the guy who did that simultaneous & incremental thing so well. That sounded like good fun.
 
jQuery in Action, 2nd edition
 
subject: user documentation
 
Similar Threads
Documentation Glossary
Agile Practices (Methodolgies)
Refactoring, extreamProgramming, Agile Modelling, SCRUM
Agile methodology V/s RUP
Agile Development - looking for more information