Re: [Evolution] FAQ vs User Docs

[Andre Klapper <ak-47 gmx net>]

> > Could you elaborate a bit?

On Wed, 2012-03-14 at 11:15 -0500, Dan Saint-Andre wrote:
> I've been making "documentation" for decades. In days of olde,
> documentation has several distinct parts:

Oh whou, thanks for explaining this - I really appreciate it and it
provides a "We've come a long way, baby" feeling.

> "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

That sounds like the Evolution manual that was shipped until version <=
3.0, in the style of "Click Save to save": Something I would not call
"Help" without feeling slightly ashamed.

> "Theory of Operation"
> "Operator's Manual"
> "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.

For the Evolution user documentation for version >= 3.2 your description
of "User's Guide" seems to fit the most.

> "Maintenance Manual"

> 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.

Oh, to me this is ontopic and I'm interested in feedback. If you have
specific issues with the user help for version 3.2 or newer (online at
http://library.gnome.org/users/evolution/3.3 ) I am happy to look into
them if you could elaborate.

andre
-- 
mailto:ak-47 gmx net | failed
http://blogs.gnome.org/aklapper