Re: Troubleshooting Vs Release Notes

Subject: Re: Troubleshooting Vs Release Notes
From: Sarah Lee Hauslinger <slhauslinger -at- gmail -dot- com>
To: Sion Lane <slane -at- ubq -dot- thrupoint -dot- net>
Date: Tue, 31 Jan 2012 13:32:24 -0800

My take is that if it always happens no matter what, it's a known
issue, which belongs in release notes.

Regarding the sometimes-and-sometimes-not scenario, compiling the
details in a troubleshooting section is just one approach.
Alternatively, though, you might consider weaving the info snippets
into the body of the guide in the most relevant locations as alerts
(Note/Important/Tip, etc.) Seems to me that from a usability
standpoint, providing the details of the "gotchas" right at the point
where they could crop up is mayhap a better option, as it doesn't
require users to jump to a different topic when something suddenly
doesn't behave as expected.

Hope this helps.

Sarah Lee Hauslinger
slhauslinger -at- gmail -dot- com

On Tue, Jan 31, 2012 at 6:58 AM, Sion Lane <slane -at- ubq -dot- thrupoint -dot- net> wrote:
> I'm wondering if anyone has any guidelines they use to decide what goes
> into the Troubleshooting section of a guide and what is more appropriate in
> the known issues/limitations section of a release note.
> At the moment, I'm working on the theory of 'if it only happens
> sometimes/on some devices/on some configurations, it goes in
> Troubleshooting' and 'if it always happens whatever you do or whatever
> you're using, it goes in the release note'.
> Anyone got any better ideas?

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
or visit

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

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Troubleshooting Vs Release Notes: From: Sion Lane

Previous by Author: Re: Android devices
Next by Author: FrameMaker book folder organization
Previous by Thread: RE: Troubleshooting Vs Release Notes
Next by Thread: Meet Us in Memphis @WritersUA - the Contest Continues

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

Sponsored Ads