Re: Software Manual Overview

[Sandy Harris <pashley -at- storm -dot- ca>]

walden miller wrote:
 
> A "Quality Software Manual" includes
> 
> 1. everything a user needs to know to install the host hardware

Not usually. I've used mainframe software without ever seeing the
hardware, let alone having to install it. I also use applications
that run on web servers, perhaps on another continent.

Even for an application that is going to run on my desktop, you
can just tell me I what I need -- computer type, miniumum hardware
resources, OS, support software -- and give references for more 
info in case I need it.

> 2. everything a user needs to know to install the software

Not necessarily. This may be in a separate document, either an
administrator's guide or just an installation guide. Many users
don't need to install or configure the software.

> 3. everything a user needs to know operate the software

Basically, yes, but there are limits. Consider an accounting
package, an architectural drawing package, or a programming
language. You may need to be an accountant, architect or
programmer to operate the software, but in general the docs
should assume those audience skills rather that trying to
teach them.

On the other hand, the package may be used by less qualified
folk. For them, you need to provide at least links to some
good resources, and often some explanation of the basics.

> 4. As much trouble-shooting information as possible

Yes, yes, 1000 times yes!

But again, this may be in separate documents. In some
environments, all the end user needs to know about
software troubleshooting is who to call. Most of the
troubleshooting info might be in an admin guide or in a
separate doc written for the helpdesk staff, rather than
in the end user doc.

However, no matter what else you provide, the end user
doc should have at least basic troubleshooting info. 

5. (at least in some applications) interface information

Consider a simple example, a word processor. The things
I can think of offhand that should probably be somewhere
in your docs (and often aren't) include:

5a) Details of the file formats used:

I'd like enough info to write, say, a Java app that
displays your format over the web, a database that
indexes the docs I've saved in your format, ...

If you use some standard format, it is enough to link
to the standard definition.

5b) Packet formats for anything you put on a wire

5c) API documentation:

Once I've got the database indexing the docs in your
format, I might like to pull out sections and display
them. Of course, you've already written code to display
your format. I don't want to re-invent any wheels. How
do I use yours?

5d) Interface to other apps:

I have technical drawings, illustrations, spreadsheets, ...
How do I incorporate these into documents?

5e) Interface to standard formats:

How do I convert a doc to HTML, Postscript, PDF, ...
Are any external tools needed?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
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.