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

["Michele Marques" <mmarques -at- cms400 -dot- com>]

"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 
information).

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