User vs Reference Guide

[Karen]

How would you differentiate a User Guide from a Refence Guide?

For so many software programs, it appears that a User Guide is just a hodge-podge make-up of everything but the kitchen sink!

Karen

[Joe Malin]

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

> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats or
> printed documentation. Features include single source authoring, team authoring,
> Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
>
> Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
> full Unicode support. Create help files, web-based help and PDF in up
> to 106 languages with Help & Manual: http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as jma...@jmalin.com.
>
> To unsubscribe send a blank email to
> techwr-l-u...@lists.techwr-l.com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/jmalin%40jmalin.com
>
>
> To subscribe, send a blank email to techwr...@lists.techwr-l.com
>
> Send administrative questions to ad...@techwr-l.com. Visit
> http://www.techwr-l.com/techwhirl/ for more resources and info.
>
>
>

--
------------------------------------------------------------------------

*Joe Malin*

jma...@jmalin.com <mailto:jma...@jmalin.com>

[Pro TechWriter]

That's a good question. I won't repeat what Joe said, because I agree with
him. My experience has been:

User Guides are for "general" users of the software; the document includes
procedures by *function* to use the program (i.e., How to access the...,
Printing, Entering ...data, and so on)

Reference Guides (sometimes also called "technical references") are usually
for a "speciality" audience, like programmers, database administrators, and
so on. This guide would contain program, database, or code information (such
as screen layouts, database tables, codebases), usually in alpha-numeric
order, sometimes grouped by program function, database table, and so on.

I hope this helps.

PT

On 2/20/07, Karen <ekarensk...@yahoo.com> wrote:
>
> How would you differentiate a User Guide from a Refence Guide?
>
> For so many software programs, it appears that a User Guide is just a
> hodge-podge make-up of everything but the kitchen sink!
>
> Karen
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats or
> printed documentation. Features include single source authoring, team
> authoring,
> Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
>

> Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,

> full Unicode support. Create help files, web-based help and PDF in up

> to 106 languages with Help & Manual: http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as pro.tec...@gmail.com.

>
> To unsubscribe send a blank email to
> techwr-l-u...@lists.techwr-l.com
> or visit

> http://lists.techwr-l.com/mailman/options/techwr-l/pro.techwriter%40gmail.com

>
>
> To subscribe, send a blank email to techwr...@lists.techwr-l.com
>
> Send administrative questions to ad...@techwr-l.com. Visit
> http://www.techwr-l.com/techwhirl/ for more resources and info.
>
>

--
PT
pro.tec...@gmail.com
I'm a Technical Technical Writer!