On Fri, 7 Nov 2003, Henry Baragar wrote:This works for me.I strongly believe that our problem solving process (for binc) should always start with the log files. Frequently, we can only make wild speculations and need the information in the log files to improve our speculations.
Very often true.
Consequently, I have three requests: 1. Can we establish a protocol that there is no log information that we always reply to requests for help with a "What do the logs say?"?
We could even ask wether the user has visited the FAQ and Life With Binc IMAP. If we can get the troubleshooter up to speed there, I think this will be quite optimal.
Since there are several things that can improve response time (and quality) on this mailing list beyond including log output, I believe we should add a section on what to do before posting to the list, and how to post. Then when users post directly with little information, we could go
Have you visited http://www.lifewithbincimap.org/index.php/Main/HowToPost ?
2. Can we add the
"http://lifewithbincimap.org/index.php/Main/HelpItDoesntWork"; link to
a. the installation instructions
b. several places in the FAQ, including as a separate topic
c. the binc home page (http://www.bincimap.org/), maybe next to the FAQ
(same line) and in the "Discussions" section
These are the places that came to mind immediately: it probably should be
posted other places.
There is currently a link to the Wiki from the home page, and it is next to the FAQ. The Discussion section could have a link to the HowToPost or BeforeYouPost sections (that don't exist yet). I will add links to the README, because this is something we need.
3. Can solicit for a few volunteers to update "Help, It Doesn't Work"
whenever a encounter and solve a new type of problem? I think that if we
have 2-4 people that are thinking about updating the problem resolution
procedures that we quickly cover 99% of the problems that people encounter
when using binc. I (of course) would be one of the volunteers.
Agreed. Of course anyone can contribute here. I'll try to update the Wiki when I encounter new problems.
The HelpItDoesntWork section could need some structuring though; we could need to seperate at the root level with common starting points:
- My connection is dropped \_ Was the imap server installed correctly? - Binc IMAP hangs \_ Does logging work? \_ Firewall? - Authentication failed \_ Are you using regular unix accounts?
At the conceptual level, your structure works well. However, most first time binc users do not have a clear conceptual understanding of binc and its operational beahaviour (other than it is an IMAP server). That is, most first time users would unlikely not be able to tell the difference between the three starting points you listed. All they know is that they got a (probably confusing) error message from their IMAP client and are very unsure about how to start looking for the root problem.
The procedures that work best for first time users are those that are very mechanical and have the users looking for specific information in specific locations (e.g. error messages the log file). If the application is well designed (as is binc) then new users quickly will pick up the concepts during the execution of the procedures. Furthermore, the more mechanical the procedures, the more likely that the procedure is followed as expected and the less need there is to question if previous steps had been followed. For example, a new user is not likely going to know that the config file must be checked to confirm that the regular unix accounts are being used: they may assume it because that is the default for a vanilla install, even though they may have installed binc from some place else that has a different default authentication method.
Note that good mechanical procedures also work well for experienced users since they are usually the same steps the experienced user was going to follow (or has already followed) to solve the problem. I recently read a paper on this and could find the reference if you would like.
<SIDE NOTE>
I would like to see severity level tags added to the error messages, where the severity indicates the capability of a client to communicate with the server. For example, an "error" level would indicate that the client cannot communicate (authentication failure, connection timed out, etc.); "warning" would indicate failed actions (folder creation failure, etc.); "info" would indicate other information and statuses; and "fatal" indicate the reason for an abnormal server exit (if possible). Then, we could search for "error" and "fatal" in the logs when there is a problem. Or, better yet, such searches could identify problems our clients have encountered, but not yet reported.
</SIDE NOTE>
And so on.. then we could add sections as we handle requests from users.Yes, that is the problem... the FAQ has more information!-) When I have a problem, I WANT IT FIXED RIGHT NOW, particularly if I have a thousand users screaming at me (which fortunately, I personally don't). I want go to www.bincimap.org and click on a clearly labelled and easily found link near the top of the page that takes me directly to the problem resolution procedures. I already know what binc is, why you started writing, its advantages, etc., etc., etc (ref: http://www.bincimap.org/bincimap-faq.html). After all, I have already downloaded it, compiled it and installed it (hopefully). I just care about my problem and solving it as quickly as possible:-). Even though the problem resolution procedures are a form of FAQ, they are used in a different way and at different time then the rest of the FAQ. For that matter, the FAQ needs to refer to them. But, there needs to be a short cut from the binc home page.
BTW, I am thinking about copying/transforming some of the FAQ (e.g the
"Server broke..." question) into the "Help, It Doesn't Work" pages.
However, I do not like the idea of maintaining two different versions of
the same information because then both versions have to be updated when
something changes. What are your thoughts on this and how would you like
to proceed.
I would actually like to think of it the other way around; the Wiki should
be the "depository" from which I pull out essential information used to
build up the FAQ. Right now the FAQ contains more information, so I guess
it's okay to just transfer some information over.
Who is goint to update the wiki when it differs from the FAQ (e.g. because the FAQ was changed)?
But don't worry about duplicating information - the FAQ is something I
I agree that the problem resolution procedures should be included in the tarball. One possibility would be to use a web site scraper to grab them from the wiki.can maintain. The FAQ is bundled with the tarball and needs to act as sort of an "offline help", and it can refer to the Wiki.
ps. This message might really belong on the binc-dev list. HB
binc@ is fine ;-).
Andy
-- Andreas Aardal Hanssen | http://www.andreas.hanssen.name/gpg Author of Binc IMAP | "It is better not to do something http://www.bincimap.org/ | than to do it poorly."
-- Henry Baragar Principal, Technical Architecture 416-453-5626 Instantiated Software Inc. http://www.instantiated.ca
