We have moved at community.getvera.com

Author Topic: Debugging Techniques  (Read 10327 times)

Offline RexBeckett

  • Beta Testers
  • Master Member
  • *****
  • Posts: 3891
  • Karma: +483/-12
Re: Debugging Techniques
« Reply #15 on: April 26, 2014, 07:07:22 pm »
I am running Win7, Vera3, Pleg 6.7, and IE.

There have been numerous issues reported when using IE with Vera. MCV recommends FireFox. Personally, I use Chrome and so, I believe, does @RichardTSchaefer so it's a good choice for working with PLEG.

[By the way, I have several suggestions for the Pleg Basics document (which is generally excellent) and would be happy to forward them to you if there is a way.]

Is this something you could PM or does it need to be emailed?

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #16 on: April 26, 2014, 11:15:56 pm »
To: Rex
I'll switch to Chrome and email my suggestions.

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
PLEG Status Report stopped updating and fix
« Reply #17 on: April 29, 2014, 04:35:47 pm »
I use Chrome and so, I believe, does @RichardTSchaefer so it's a good choice for working with PLEG.
On 25 Apr, I reported that I was having trouble getting the PLEG Status Report (on the Control tab) to update.  RexBeckett suggested switching to Chrome, from Internet Explorer 10 that I had been using when the report froze up.  This reply is to confirm that switching to Chrome has apparently solved the problem: the Status Report is now updating consistently.  I also tested using Safari on an iPad 1, which seems to work as well.

Offline awake33

  • Sr. Newbie
  • *
  • Posts: 33
  • Karma: +1/-1
Re: Debugging Techniques
« Reply #18 on: June 20, 2014, 04:11:55 am »
If we're going to play the "I spent X years dong Y" card, then I should pre-declare that I used to write user documentation for a living for a software company you've all heard of.  I now develop software at the same company and I routinely deal with eight languages on a day-to-day basis and about a dozen more on rare occasions.  (Of course, this counts for nothing except to suggest how susceptible I am to the Dunning-Kruger effect.)

The instructions that you have provided while useful, and perhaps even complete, to an experienced user assume a good deal of knowledge that many trying to get started will find leaves large gaps.  It does not mean we are incapable, but just inexperienced at things you take for granted.

Over in psychology-land, they call this the gap between the Curse of Knowledge and the False-consensus effect.  The writer of the documentation glosses over something "obvious", incorrectly assuming that anyone will have the necessary skill.  The reader of the documentation doesn't know how to perform that step, and incorrectly assumes that everyone else would have stumbled at the same point, faulting the documentation.

Where does the fault lie?  It doesn't matter.  The crucial thing is for both parties to work to bridge the gap.  Here is the process we would follow in my day job:

1. The writer of the documentation produces a series of steps, and numbers them.  Each step contains only one imperative verb.
2. The reader of the documentation tries to perform the steps, and when they get stuck, they report which step they were on, what they expected to see and what they actually saw.
3. The writer and reader figure out what the miscommunication was, and arrive at a new, possibly more detailed, series of steps.
4. Goto 1.

As a writer of documentation, I would always have to assume a certain level of knowledge of my users.  I'm going to say: "Open your browser", not "Press the Spotlight icon then type 'Safari' and press Return" because the latter is actually less helpful, particularly to Windows users.  I'm going to say: "Edit the file in a text editor", not "Right-click on the file, select 'Open with...' and choose 'Notepad'" for the same reason.  Too much detail is as much of a turn-off as too little.  (Digression: here on the forum where I earn $0 an hour for my work and where I assume that users are more motivated, I'll sometimes set them homework to achieve a task, by deliberately not spelling out something that I think they can learn for themselves.  If you dislike this you can complain to my manager.)

So, with the above process in mind, and understanding that it's an iterative process:

Richard: Number your steps.  Users like numbered steps, and it gives them something to refer to.
quinn: Assuming that you followed Richard's steps, where did you get stuck?  It's not obvious to Richard; remember that he has the Curse of Knowledge.

All due respect, I'm not sure I would be advertising that such knowledge is the backing of some of the worst documentation that exists in the IT industry. I've been working in the IT support realm for over 20 years, and it is a running joke that Microsoft's "Help" is helpless, unless you like chasing your tail and going in circles. It has invariably been more useful and valuable to perform a search that employs the knowledge of real world users that hang out in forums than to attempt to utilize documentation from Microsoft itself. While the subject matter you mention is actually quite fascinating, it only makes it seem that MS should be that much more embarrassed by the shortcomings of its documentation for its various software offerings (especially the deeper workings of the server OSs and Exchange).

My apologies if my assumption that we are talking about Microsoft is incorrect, and on a side note, the lack of usefulness of Microsoft's documentation for anything but the most trivial and mundane of operations is all too common for gigantic corporations as they seem to lose touch with the real user base (Metro interface, anyone?).