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: If you were making a FAQ... From:Paul Hanson <twer_lists_all -at- hotmail -dot- com> To:"'McLauchlan, Kevin'" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 30 Aug 2012 15:59:14 -0500
See below:
-----Original Message-----
From: techwr-l-bounces+twer_lists_all=hotmail -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+twer_lists_all=hotmail -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of McLauchlan, Kevin
Sent: Thursday, August 30, 2012 3:03 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: If you were making a FAQ...
a) Would you include it in online help (WebHelp) if that was the
primary documentation for your product?
>>>>It depends
b) If yes, then would you make it one big FAQ topic/page, or would you
make each Q and A a separate topic/page under a FAQ "book" in the ToC?
Why?
>>>>> Here's my take on FAQs.
I used to work at a company that had a long procedure to add a XYZ to the
system. One of the tasks I completed while I was there was an audit of that
procedure and it expanded to something like 34 steps (totally breaking the
+/- 7 rule but don't go there). That revision was reviewed by Development
and added to the online Help.
Unbeknownst to me, that same procedure had, long ago, been added to a FAQ
section of the company website, within the "clients" area. The procedure in
the FAQ was a measly 17 steps.
So right there, it is different from your situation where the FAQ could be
part of the online Help for the product. I'll just say that if you do
include a FAQ in the help, do not repeat the same procedure in two places.
The story continues...
A while later, a client called in to Support to complain (imagine that!)
that he couldn't see the XYZ he had added to the system in an area of the
system he expected to see it. Long story short, it was not in the procedure
on the website, but was included within the procedure in the online Help. He
was using the FAQ version of the procedure. We redirected him to the online
Help and he was good to go.
In that world, the FAQs were not updated routinely.
What should happen is that the FAQ should be changed to point to the online
Help, especially when there is a dedicated resource to update online Help.
If it can be a hyperlink (in that world, all online Help was local on the
C:\ so that was dismissed as an option (what if the client didn't have
online Help installed?).
I think it should go:
Documentation is released for a software version ==>
Client/Support/SOMEONE identifies the documentation needs a change ==>
A FAQ is written to get the client by ==>
the TWer updates the documentation for the next release ==>
when the updated help is released, the FAQ is changed to point to the
updated procedure in the help, thereby removing two versions of the same
procedure.
The online Help becomes the Master and the FAQ is the slave to it. You can
have it as part of the online help or not - just don't duplicate content!
That's my opinion. It's worth what you paid for it.
Paul
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
