RE: If you were making a FAQ...

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.

http://bit.ly/doc-to-help

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

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


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

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
If you were making a FAQ...: From: McLauchlan, Kevin

Previous by Author: RE: LaTeX and output to MS-Word
Next by Author: RE: Too many steps, take some out (was RE: If you were making a FAQ...
Previous by Thread: RE: If you were making a FAQ...
Next by Thread: Re: If you were making a FAQ...


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


Sponsored Ads