On Wed, 2012-03-14 at 15:31 +0000, [email protected] wrote: > Message: 3 > Date: Wed, 14 Mar 2012 14:42:59 +0100 > From: Andre Klapper <[email protected]> > To: [email protected] > Subject: [Evolution] FAQ vs User Docs [was: reanimation of backup] > Message-ID: <[email protected]> > 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
_______________________________________________ evolution-list mailing list [email protected] To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-list
