Documentation size and ease-of-use (of documentation)

Subject: Documentation size and ease-of-use (of documentation)
From: "Michele Marques" <mmarques -at- cms400 -dot- com>
To: "TECHWR-L digest" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 8 Sep 1999 11:41:35 -0400

"Murrell, Thomas" <TMurrell -at- alldata -dot- net> says:
> Final Thought: A simple documentation set might not be the one with
> the fewest pages. It might be the one that is easiest for users to use
> and might actually contain more pages than would, at first glance, seem
> necessary. It all comes down to what gets the message across the best
> to the target audience. It is hard work, and it also can be very
> rewarding.

Our company's main product is an ERP system. As the system is quite
large, the documentation is also large. When I started, one of the higher
ups told me that customers complained both that there was too much
and not enough documentation. He was a bit perplexed by this seeming
paradox, but I took it to mean that customers are overwhelmed by the
quantity of documentation, but cannot find the information they need (or
perhaps are overwhelmed by the quantity when trying to locate

I have taken two approaches to improving usability of our
documentation (with positive customer feedback). First, I came up with
and have been applying (when updating or revising documents) a style
guide that is appropriate for reference materials. It is now easy for users
to locate information in a given chapter. Previously the documentation
had been written as a hybrid users guide and reference guide; I dropped
the users guide approach, as that information is covered in
comprehensive training (and would be most appropriate - in our situation
- in training workbooks).

Second, I have been improving the indexing of our documents, including
cross-references. In a large system, one of the problems can be that the
user does not know what other procedures are relevant to his task; when
there are related procedures (either through similar functions or from one
procedure being prerequisite to another), I refer to the other procedures
and explain the relationship in the overview of a procedure.

My favourite large set of documentation was for SAS (statistical
package). At least at one point, the documentation included a 2-volume
user guide (which included basic common procedures), many reference
volumes, and an index volume. The reference volumes were divided into
related functions (and alphabetically within volume or between volumes
on the same theme). The reference volumes were consistent, and it was
easy to locate information.

Michele Marques
Technical Writer, CMS Manufacturing Systems
mmarques -at- cms400 -dot- com
905-477-4499 x280

Previous by Author: RE: TW for embedded systems
Next by Author: RE: Tape Recording End Users & SMEs
Previous by Thread: RE: techwr-l digest: September 07, 1999
Next by Thread: Re: Documentation size and ease-of-use (of documentation)

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

Sponsored Ads