TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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. http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
