RE: Options

["Jay Hammond" <jaychammond -at- hotmail -dot- com>]

Robert and Gerry;

You both asked about documenting a large software application with multiple 
options. This is much harder than it sounds, believe me. I've been doing it 
for more than a year and still don't think I'm developed the perfect method, 
but here are a few things I have learned along the way:

1) Use a tool designed for authoring large documents. I'm using Framemaker 
which easily converts into .pdf format for online use and I highly recommend 
it. If you don't care about formatting, xml may be another good choice, I've 
used it for some mid-sized docs and while I don't think it will do as well 
with large documents, it's handled the smaller ones just fine. HTML works 
too, but we've encountered some printing issues not to mention it's easier 
for user's to alter which gets them into all kinds of trouble.

2) If you can, stay away - far away - from customizing documentation for 
individual clients. Until you have a strong document architecture to build 
on, this can be a nightmare and you can end up with the same option being 
documented in multiple places and rarely will it be documented the same way 
twice. It also makes maintenance more of a challenge. If this is the 
direction you want to go, invest in some top quality content management or 
single sourcing tools first.

3) Plan ahead!  You'll be amazed at how many options can be added to a 
single application. Even if they all seem manageable now, chances are, they 
will threaten to get out of control at some point. So take the time to 
figure out how you will address added or changed functionality within your 
docs -- will you update everything, release individual chapters/smaller 
books, will you provide a summary of changes, etc. Also, try to determine 
how frequently you will update documentation, the longer you can wait 
between updates, the easier the process is to manage.

4)  Implement a formal documentation review process and involve both the 
software developers and customer support. These folks will either know how 
the stuff was designed or how your customers use it and can provide 
incredibly useful information you might otherwise miss.

5)  Set up a decent method of archiving your documents. This way there is 
some traceability of what was done when and how. This can be especially 
helpful if you don't have detailed design documents to work with.

6)  This last one is purely my preference: but I suggest you organize your 
user manuals by task and your online help (if any) by module. This is 
because people who read manuals generally are trying to learn how to do 
things as opposed to people needing online help from within the application.

That's all I can come up with off the top of my head, but I'll be happy to 
provide additonal perspective if you have specific questions!

Jay Hammond
Information Development Manager
Mesa, Arizona, USA

_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.