On Mon, 10 Nov 2003, Henry Baragar wrote:I still think this is one step too many for a paniced or lost user, but it is getting better.Could you please expand on your ideas for a wizard? What do you envision?
Okay; I've installed Binc IMAP, but when clients try to connect, they just
hang and nothing happens. So I visit the bincimap.org site, which tells me
to visit the lifewithbincimap.org site. There, I click the
"HelpItDoesntWork" link.
On this page, I see a small collection of general problems:But I believe the purpose of the page is to accurately and quickly diagnose the problem and we have to be very careful not to assume that the user has already done something that you and I would do naturally. We can't jump to conclusions and we do not want the users to jump to conclusions; otherwise we all end up chasing phantom problems.
While I believe the first and last items in this list are good examples for such a page, I think that the middle two assume the user has already done some problem diagnosis. The questions now are: did the follow a procedure that is equivalent to the one that we would use and has the user properly interpreted the symptoms?
* It won't compile! (link to installation pages) * Binc IMAP hangs * Logging doesn't work * Users can't log in
Speaking of jumping to conclusions, I jumped to the conclusion that binc IMAP had been installed and had been operating when I started HelpItDoesntWork. A better starting point might be:
* It won't compile/install
* Its compiled and installed, but I can't get it to work
* It was working, but now there's a problem
We need to start with the first symptoms that were observed by the user and then provide a procedure to the gathering more symptoms until we have enough information to diagnose the problem.
BTW, I am not sure that "It won't compile/install" should refer back to the installation pages because that is likely from whence the user just came: they were following the installation procedure and encountered a problem that was not discussed in the installation procedures (or they could not find it in the installation procedures).
If the user was capable of figuring out these causes, he/she is very likely able to figure out the solution. The challenge (which is very difficult for us because we know binc so well) is to capture the procedure that we use (or would use) to get to this point.Clicking on "Binc IMAP hangs", I get a list of suggested causes which I can check for, and possibly links that can take me further in my search for a solution:
Binc IMAP hangs \_ Cause: Logging | \_ I'm using multilog | | \_ Is the multilog process running? | | \_ etc.. | | | \_ I'm using syslog \_ Cause: checkpassword is hanging | \_ I'm using the standard checkpassword | \_ I wrote my own | \_ I'm using checkpassword-pam \_ Cause: Firewall
BTW, I assume this is only an example and you don't really expect a firewall to cause binc to hang?-)
Writing good problem determination procedures is at least as difficult as writing a good user manual. Just as for the user manual, the writer has to shift his/her mindset from the designer/developer point of view to the end user point of view. Having written a few diagnostics manuals (for complex systems), I can tell you my three goals:
1. Make the procedure specific, consistent and repeatable: deviations lead to miscommunication, even if the deviations provide an equally valid alternative procedure
2. Create a decision tree where the decisions are based on specific observations and symptoms: the best ones usually come from well written log messages
3. Structure the decision tree to be of minimum depth with each node based on only one observation: this gives the best speed without sacrificing accuracy
These are my opinion:-)
Henry
Similar to the troubleshooter in Windows, which is one feature I think M$ got right.
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
