Re: [Evolution] FAQ vs User Docs

[Dan Saint-Andre <saint grillongroup org>]

On Wed, 2012-03-14 at 15:31 +0000, evolution-list-request gnome org wrote:
>     Message: 3
>     Date: Wed, 14 Mar 2012 14:42:59 +0100
>     From: Andre Klapper <ak-47 gmx net>
>     To: evolution-list gnome org
>     Subject: [Evolution] FAQ vs User Docs [was: reanimation of backup]
>     Message-ID: <1331732579 1967 35 camel embrace foo>
>     Content-Type: text/plain; charset="UTF-8"
>     
>     On Wed, 2012-03-14 at 07:52 -0430, Patrick O'Callaghan wrote:
>     > Milan, there's a warning at the top of that page to the effect that the
>     > FAQ is no longer maintained and no material should be added to it. I
>     > personally consider this a big mistake as in my view a FAQ and a
>     > reference manual are two different things, plus the FAQ is much more
>     > convenient as a reference point for specific issues, but that's how
>     > things currently stand.
>     
>     I'm the one to blame as I added this. IMO anything that helps the user
>     should be in one central place - in the user docs. I don't consider the
>     user docs a "reference manual" (not sure what that term means).
>     And I welcome patches. :)
>     
>     The problem might be where to make the cut - what is still a
>     *frequently* asked question and what it isn't.
>     
>     Could you elaborate a bit?
>     
>     andre 

I've been making "documentation" for decades. In days of olde, documentation has several distinct parts:

"Reference Manual" -- list every button and option and input with explanation of what behavior they caused in the
creation of results;  show every output with explanation of what they mean and what happened to create that output

"Theory of Operation" -- Considered, by some, to be part 2 of the "Reference Manual," the Theory of Ops manual
included the WHY explanation in support of the Reference Manual's WHAT.

"Operator's Manual" -- a comprehensive description of how one fed input data and options, messages and announcements,
and gathered results.  If an application could take data from other apps and provide results as input to other apps,
the Operator's Manual detailed how to make that happen from the perspective of the data interfaces -- each app stood alone.
As the word "operator" implies, these were intended for data center folks.

"User's Guide" -- a subset of the Operator's Manual that explained how desktop workstation folks could obtain results.
If well written, these guides might start with "If you want these results ..." and explain how to feed data and options to 
cause those results to happen. In addition, there might be sections that begin "If you have this data ..." and explain
all of the results one might generate with that information as a starting point.  Both perspectives are important.
As the word "user" implies, these were intended for folks use in years after the data center managed processing.

"Maintenance Manual" -- while most often used when there is hardware involved, an application maintenance manual 
might explain database housekeeping, corrective actions based on a catalog of error messages, (heaven forbid) interpretation
of any "error codes" or "numbered messages", data file structures, and other technical tidbits used to fix the 
application should something go wrong.  Most important, there were various procedures to aid folks in discovering
whether the application was running correctly or not including an installation verification process.

I know this is off the topic of "Evolution -- the email client" but I continue to be frustrated by the state of what
passes for "documentation" for what could be a pretty decent application suite.

Scribbling away,
~~~ 8d;-/ Dan