Troubleshooting?

Subject: Troubleshooting?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, obair81 -at- comcast -dot- net
Date: Fri, 19 May 2006 09:39:39 -0400

Paul wondered: <<I am tempted to place my nascent Troubleshooting section into my release notes, which now have these sections: - new features - Changes - closed issues - known issues Is there any real reason to keep a Troubleshooting section at the end of my main admin guide?>>

Interesting question. The problem with release notes is that not a lot of people read them. We do, for sure, but we're Geeks, and not necessarily representative of the larger world. Indeed, RTFM was invented because people don't even read the main printed docs, let alone release notes. <g>

The advantage of placing troubleshooting information in the release notes is that much of it will be tied directly to the instructions and procedures that produce problems. I've been a long-term advocate of placing troubleshooting information directly in the steps that we know are most likely to cause problems*--in effect, to divide such steps into two parts, namely "here's what you should do" and "here's how people routinely screw up this step and how you can tell whether you succeeded or whether moving on to the next step will only add to the mess".

* Of course, the real fix is to build a solution into the software. For example, I just told a client that rather than specifying what language settings users should select in the Windows control panels (failure to do so causes significant problems), they should do two things: offer to make this change for the user during software installation, and write a tiny routine that runs during the launch of the software and displays the necessary advice (i.e., "you've got the wrong settings, dude; we won't allow this program to run until you make the following changes...") Why leave to chance something you can automate for the user? For that matter, why not test whether the user created a known problem after each step, and if so, pop up a note telling them how to fix it?

Nonetheless, it's traditional to place troubleshooting information at the end of the main manual, in its own section, and it's rarely a good idea to fight too hard against tradition. For example, there's no reason other than tradition why we put indexes at the backs of books. Why not put them up front with the table of contents (TOC), since both are points of entrye into the larger work? Or use the (French?) approach of putting the TOC at the back of the book with the index?

In any event, that's a digression; the real point is that you can do both: include the relevant information in your release notes for those who read them and need help troubleshooting the installation, then provide that information plus any other troubleshooting advice in the main docs, where everyone expects to find it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

References:
troubleshooting: From: obair81

Previous by Author: Living documents?
Next by Author: Placement of index and TOC?
Previous by Thread: troubleshooting
Next by Thread: Moving upstream


What this post helpful? Share it with friends and colleagues:


Sponsored Ads