Perfect Documentation

Subject: Perfect Documentation
From: Joe Fockler <jfockler -at- IPHASE -dot- COM>
Date: Mon, 25 Apr 1994 16:59:50 -0500

From jfockler Mon Apr 25 16:37:54 1994
Return-Path: <jfockler>
Received: from wildcat (wildcat_fddi) by (4.1/SMI-4.1)
id AA13974; Mon, 25 Apr 94 16:37:51 CDT
From: jfockler (Joe Fockler)
Received: by wildcat
(4.1//ident-1.0) id AA24236; Mon, 25 Apr 94 16:37:51 CDT
Message-Id: <9404252137 -dot- AA24236 -at- wildcat>
Subject: The Perfect Manual
To: techwr-l
Date: Mon, 25 Apr 1994 16:37:50 -0500 (CDT)
X-Mailer: ELM [version 2.4 PL23]
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Length: 2552
Status: OR

What is the ultimate and/or nearly perfect User's Guide or manual?

My department is investigating ways to vastly improve our
documentation - content, attractiveness, ease of use, etc. Presently we
use an 8 1/2" x 11" format for our OEM User's Guides, and a 5 1/2" x 8
1/2" format for our Enduser User's Guides.

The OEM guides are typically pretty large and include:

1. General Information on the particular bus and technology (SBus,
VMEbus, FDDI, SCSI, ATM, Ethernet) that the product is based on.
2. Hardware Installation and jumper settings.
3. Available commands for those writing their own device driver.
4. Specifications, Diagnostics, Simple Tutorial on the technology,
Troubleshooting, Index, etc.

The Enduser guides typically contain:

1. Introduction -- Features, Compatibility, System Requirements,
Introduction to the technology (FDDI, ATM, etc.)
2. Software Installation
3. Hardware Installation
4. Troubleshooting
5. Specifications
6. Index

We want to make all of our documents homogeneous as possible. I have seen
many people on this list referred to Hewlett-Packard documents or Sun
documents as the standard. We are looking at perhaps separating our
manuals in the following manner:

1. Installation Guide
2. Technical Reference Guide
3. ??? Getting Started

Do you have any thoughts and ideas as to what makes a manual or document
set great? Who sets the standard to emulate? What is the most effective
approach for a consistent look for these two different markets? The OEM
users are technical, and the endusers want a product that they can plug
and play.

Any ideas, advice, input, suggestions, comments, criticism, and wisdom
that you can provide will be most appreciated. Please let me know what your
company does, or what you would like to do. In your opinion, who has the
ultimate user's guide(s)?

Thank you for your input.

Highest Regards,

Joe Fockler
jfockler -at- iphase -dot- com
Technical Writer
Interphase Corporation
Dallas, TX 75234

Previous by Author: Re: Prepositions ending sentences
Next by Author: Re: Help with phrasing
Previous by Thread: Re: Computer Writers
Next by Thread: Re: Perfect Documentation

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

Sponsored Ads