Re: User vs Reference Guide

[Joe Malin <jmalin -at- jmalin -dot- com>]

I use a fairly rigorous scheme for dividing information by type:

   * concepts - overviews, theories, how it all fits together
   * reference - details, syntax, allowed values, results of allowed
     values, file formats
   * procedures - how to do common tasks, but usually small focused
     ones like install something, convert something, etc.
   * tutorials/examples/guidelines - a mixture of types, focused on
     helping people use a complex architecture, usually for software or
     hardware developers using an architecture.
   * organization (ie TOC)

When I use the term "User Guide", I mean something that primarily 
contains concepts and procedures. I sometimes use "Reference", but not 
"Reference Guide". So, I might have

The Foo User Guide - What Foo is, how to compile Foo programs
The Foo User Guide and Reference - What Foo is, how to compile Foo 
programs, Foo language syntax
The Foo Programmer's Guide - All the procedures for compiling and 
linking Foo programs, plus any auxiliary tools like the Foo debugger, 
the Foo Universal RPM Mistake Finder, etc.
The Foo Tutorial - Concepts of Foo, explained with hand-holding code 
examples, etc.
Foo Developer Guidelines - tips and tricks for accomplishing real-world 
tasks in Foo

A User Guide should not, ideally, be a hodge-podge. I think you can put 
everything but the kitchen sink in it, as long as it's obvious that 
you're not offering any other books. If you do put in everything, you 
really should organize it by information type. I am convinced that poor 
technical writing comes from mixing information.

Joe


Karen wrote: