• 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 Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

user documentation

 
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
(instanceof Sidekick)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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?
 
author and iconoclast
Posts: 24207
46
Mac OS X Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Zsuzsa Nagy
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
author
Posts: 608
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Ilja Preuss
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic