• 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

Agile user documentation and doc processes

 
Author
Posts: 377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Scott,
Speaking of the shelf-feet of manuals mentioned in another topic, I'm hoping to learn something agile techniques and technical writing. (I've been in the techwriting/training field for 13 years.)
As I understand Agility generally (fuzzily), one of the assumptions is that documenting as you go along isn't a good idea since the docs are always out of date and wrong. I'm on board with that. I also understand that on some projects the users are bidden to fiddle with the prototype and give feedback as things go along, which means that there isn't necessarily a solid UI or set of specs for the techwriters to document to.
I have a few questions about how agility affects docs and doc processes:
- Generally, what is the effect of agile techniques on the techwriters who work with the agile programmers, and the docs they produce?
- Can techwriters apply agile development techniques to techwriting?
- Is there something else techwriters can do besides try to help make the UI as logical and easy as possible, thus requiring less documentation? (I've helped create a couple systems that simply suck data out of the program or database into a usable UI; they were very successful and a huge load of work off the TW team.)
- Do you advocate documentation being started, and when should it be finished, in a world where all managers always want the software shipped the second QA signs off on it?
- Any other advice?
Thanks,
Solveig
[ January 13, 2004: Message edited by: Solveig Laura Haugland ]
 
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 Solveig Laura Haugland:
As I understand Agility generally (fuzzily), one of the assumptions is that documenting as you go along isn't a good idea since the docs are always out of date and wrong. I'm on board with that.


I think you misunderstood. The assumption is that developers should only produce documents which are
- currently found to be needed by the developers, or
- requested and scheduled by the Customer
If the Customer wants a user manual, it might still be sensible to write it incrementally, together with the rest of the system.

I also understand that on some projects the users are bidden to fiddle with the prototype and give feedback as things go along, which means that there isn't necessarily a solid UI or set of specs for the techwriters to document to.


One of the principles of Agile Software Development (see http://agilemanifesto.org/principles.html) is "Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale."
But those deliveries are less of a prototype, but simply early stages of fully functional systems. It might be a good idea to have those systems documented when they are delivered to the users.

Ron Jeffries has some interesting articles about this topic on his website: http://xprogramming.com/xpmag/docIndex.htm
 
Solveig Laura Haugland
Author
Posts: 377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Ilja,
Re the dev docs, I was making an invisible leap in my own head. Techwriters often use the tech docs as a basis for their own docs; thus fewer docs change the standard process for what TWs often do.
Thanks for the web sites; I'll check them out.
>> Ron Jeffries has some interesting articles about this topic on his website: http://xprogramming.com/xpmag/docIndex.htm[/QB]
I'm thinking that AD could be a good way to prod ornery dev managers into including TWs in the process, via big sharp pointy buzzwords. ;> It sounds like a great system, certainly far more suited to my own workstyle than the waterfall method that is the default in a lot of dev and TW orgs.
Thanks,
Solveig
 
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 Solveig Laura Haugland:
Re the dev docs, I was making an invisible leap in my own head. Techwriters often use the tech docs as a basis for their own docs; thus fewer docs change the standard process for what TWs often do.


Yes - they would rely more on direct, face-to-face communication, and on the actual, running system.
At work, we have one TW (it's a small company). Last month we enhanced our nightly build so that it automatically deploys the system to our inhouse webstart server. That way, the TW can always work on the most current version. (It's quite cool, IMHO )
 
Solveig Laura Haugland
Author
Posts: 377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
That is VERRRRRRRRRRY cool. Oh my god. I hope he/she knows how great that is. How much time does everyone in other companies in TW and dev and everywhere waste just getting the last ##$#@&^ build to run? Excellent.
solveig

Originally posted by Ilja Preuss:

Yes - they would rely more on direct, face-to-face communication, and on the actual, running system.
At work, we have one TW (it's a small company). Last month we enhanced our nightly build so that it automatically deploys the system to our inhouse webstart server. That way, the TW can always work on the most current version. (It's quite cool, IMHO )

 
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 Solveig Laura Haugland:
I hope he/she knows how great that is.


Well, I can remember her complaining about how much time she wasted getting a running system just to make some up-to-date screenshots, so I guess she knows...
 
(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'm curious about your spot in life. As tech writer, who is your audience? What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release? Those things could seriously affect how happy you are with your agile developer buddies down the hall, no?
 
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 Solveig Laura Haugland:
That is VERRRRRRRRRRY cool. Oh my god.


I guess I have to remember that story. Wonder wether it works that way on other girls, too...
 
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:
I'm curious about your spot in life. As tech writer, who is your audience? What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release? Those things could seriously affect how happy you are with your agile developer buddies down the hall, no?


Our TW is working on both the integrated online help and the printed manuals. The manuals are still updated in a quite infrequent manner, but that's more for management reasons than for technical ones.
 
Solveig Laura Haugland
Author
Posts: 377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,
Not sure who the ? was for but heck, I'll answer anyway. ;> I'm not currently in Regular Techwriter/Software Development Life. (Am on my own doing openoffice stuff and weirder stuff.) However back in the day at Sun, BEA, and Great Plains, it seemed like the only systems we ever put in place, aka Systems With a Capital Letter and a great deal of bowing and scraping, didn't do much good and good old-fashioned brainpower and facemail and ingenuity were the best. So in case I ever come in from the cold ;> I'm looking around to see what works well for workin' with a standard organization. Not that I'm thinking I will just now, just generally.
And I am sooooo not into things being "perfect." ;> I like the quote that perfection is the enemy of the good. My happiest position was on a very agile 11-person team, doing new web stuff in 1996, I was the only techwriter, and I spewed out a new doc release every 2-4 weeks very happily.
>> What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release?
Somewhere in between the two: printed docs but I print on demand. I also do some humor books in print runs of 100 with a local printer. I guess the key factor though, is that I'm pretty much my own SME so the communication between departments is all very quick. ;>
My audience is the folks I train or that other companies train, and of course the trainers themselves. The other audience is geeks with the same twisted sense of humor I have. ;>

Originally posted by Stan James:
I'm curious about your spot in life. As tech writer, who is your audience? What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release? Those things could seriously affect how happy you are with your agile developer buddies down the hall, no?


Luckily, I'm fairly happy with inner agile developer though sometimes I wish she were more organized. ;>
Solveig
 
Solveig Laura Haugland
Author
Posts: 377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
That's a clear implementation of Unexpected Resource God! ;> (The act, not the story. Though actually one would get more connection through being the guy to do the install for the Techwriter, but these implementations do depend on instance-specific data.)

Originally posted by Ilja Preuss:

I guess I have to remember that story. Wonder wether it works that way on other girls, too...

 
author
Posts: 608
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I've inlined my responses.
- Scott

Originally posted by Solveig Laura Haugland:
[QB]Hi Scott,
SLH: Speaking of the shelf-feet of manuals mentioned in another topic, I'm hoping to learn something agile techniques and technical writing. (I've been in the techwriting/training field for 13 years.) As I understand Agility generally (fuzzily), one of the assumptions is that documenting as you go along isn't a good idea since the docs are always out of date and wrong. I'm on board with that.
Scott: That's an issue, but the real problem is that the more docs you write, the more you need to keep updated, review, ensure traceability between, ... You really want to remain as lean as possible.

SLH: I also understand that on some projects the users are bidden to fiddle with the prototype and give feedback as things go along, which means that there isn't necessarily a solid UI or set of specs for the techwriters to document to.
Scott: Agile Modeling (www.agilemodeling.com) includes a practice called Active Stakeholder Participation which says that stakeholders (including users) can and should be members of the team. They provide information, make decisions, and can even be active members of your modeling and maybe even development efforts. To accomplish this you need tools and techniques that they can use, one of the reasons behind AM's Use the Simplest Tools concept.
SLH: I have a few questions about how agility affects docs and doc processes:
- Generally, what is the effect of agile techniques on the techwriters who work with the agile programmers, and the docs they produce?
Scott: They should become active members of the team. They likely will be doing far more than tech writing though as they should strive to become generalizing specialists (http://www.agilemodeling.com/essays/generalizingSpecialists.htm). The Agile documentation essay (http://www.agilemodeling.com/essays/agileDocumentation.htm) should prove to be of interest and there is even a book by that name (http://www.amazon.com/exec/obidos/ASIN/0470856173/ambysoftinc) now.
- Can techwriters apply agile development techniques to techwriting?
Scott: Absolutely, if you choose to.
- Is there something else techwriters can do besides try to help make the UI as logical and easy as possible, thus requiring less documentation? (I've helped create a couple systems that simply suck data out of the program or database into a usable UI; they were very successful and a huge load of work off the TW team.)
Scott: I'm a firm believer that all developers should have solid UI skills, although unfortunately few people seem to understand the importance of this. In the 3rd Edition of The Object Primer (www.ambysoft.com/theObjectPrimer.html), due out in March, I include an entire chapter on the subject. It's irresponsible that most writers who cover software design to ignore UI issues, IMHO. I think we need to raise the bar a bit.

- Do you advocate documentation being started, and when should it be finished, in a world where all managers always want the software shipped the second QA signs off on it?
Scott: Take a look at the AD essay. Documentation should be treated just like any other requirement -- it should be done in priority order. Sounds like your managers need to be educated a bit. ;-)

- Any other advice?
Scott: Just keep learning and trying new stuff.
-Scott

 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic