Re: [Evolution] FAQ vs User Docs

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 ) I am happy to look into
them if you could elaborate.

mailto:ak-47 gmx net | failed

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]