Summary: One doc or multiple docs? (Long)

["Dawson McKnight" <dawson_mcknight -at- hotmail -dot- com>]

I asked:  How "consolidated" is your documentation set? Do you provide 
installation, administration, configuration, and troubleshooting guidance in 
a single document (e.g., an "Administrator's Guide"), or do you provide each 
of these kinds of instructions in a different document? Without a 
substantial user base, how can I determine how consolidated my documentation 
set should be?

Thanks to Geoff Hart, Katie Kearns, Bill Swallow, Abby Matsumoto, and Dianne 
Blake, who answered:

Reasons to break up your documentation into multiple, smaller documents:

1. You have various groups of users, each of which requires different kinds 
of information (to paraphrase Geoff Hart). This is particularly important if 
some users *must not* have access to information in certain parts of your 
documentation.
2. You are distributing printed documentation with your product, and several 
kinds of users may need physical access to a single book at the same time. 
You can, however, alleviate this problem by distributing electronic 
documentation instead of printed documentation, although this is complicated 
by item 3.
3. You are distributing electronic documentation with your product (e.g., 
PDFs), and you want to accommodate users that want to print the 
documentation on site. For example, the user would find it easier to print a 
50-page installation guide than a 350-page administrator's guide that 
contains 50 pages of installation instructions. The counter-argument to this 
approach is that most moderately savvy users would use Acrobat to print the 
relevant page ranges rather than printing the entire file. I suppose that it 
all depends on your audience's "technical-ness."
4. You are documenting software that runs on multiple operating systems, and 
each operating system requires a different version of your documentation. 
There are ways to avoid this, particularly if you are documenting 
non-command line software. The FrameMaker documentation manages to address 
several operating systems with a single set of manuals.
5. You are on a team of writers and you need to divide the labor. Assigning 
one document to each writer allows for greater document ownership and 
accounts for varying levels of experience (e.g., new and inexperienced 
writers get to write the "easier" documents). (That didn't sound too great, 
but I hope you know what I mean. :)
6. Some of your documents are modified and released frequently. Diane Blake 
writes:
"If all of the documents are normally released/modified at the same time, 
then it might be appropriate to create a single document. If however, you 
find certain documents are always in flux, then you might want to keep the 
documents that turn over more rapidly separate. This will simplify your 
change history and allow users to better understand when changes happen."
7. You are using Word to produce your documentation. Word is reputed to 
become unstable after a certain number of pages (I can't remember how many).
8. Some of your sections or documents may need to address additional 
audiences in the future.

Reasons to consolidate your documentation:

1. You only have one audience.
2. You have multiple audiences but it doesn't matter whether each audience 
knows what the other audiences should know or all audiences can understand 
the same explanations of the subject matter.
3. To quote Katie Kearns, "It isn't terribly wonderful for our users to have 
to sort through 5-10 books to find that they're looking for."
4. You are using FrameMaker or another product that makes the division of 
labor for long documents easy and that doesn't easily corrupt long files.
5. You are distributing your documentation electronically, so distributing a 
single document to multiple users does not present the same problems that 
distributing a single hardcopy manual would.

In conclusion, I'll quote Katie again:  "I don't think there is a 'right' 
answer."  I hope that this helps somebody as much as your posts helped me!

Regards,

Dawson

_________________________________________________________________________
Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com.

Share information about yourself, create your own public profile at 
http://profiles.msn.com.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

---
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.