RE: Options

Subject: RE: Options
From: "Jay Hammond" <jaychammond -at- hotmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 24 Jun 2001 08:11:02 -0700

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


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at 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

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 for more resources and info.

Previous by Author: RE: Interviews: Where do you see yourself in 5 years
Next by Author: Repeating Last Action in FrameMaker
Previous by Thread: Copyright and the Internet
Next by Thread: Did we develop a criteria for using this term: electronic business?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads