RE: Advice needed for documentation project

Subject: RE: Advice needed for documentation project
From: "Zuercher, Darrell" <dzuerche -at- tva -dot- gov>
To: "Brasel, Russell" <russell -dot- brasel -at- hccredit -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 27 Dec 2006 10:34:39 -0500

Russell,

This past spring, one of our departments decided to launch a help desk
and wanted a knowledge base for the operators to locate commonly
encountered issues and software problems. I was notified of this request
about two weeks before the plan was implemented. Using the only tool at
my disposal--RoboHelp X5--I created a knowledge base. My approach is not
pretty and is high maintenance, but it got the job done.

The help desk supports over 200 software systems. The knowledge base is
structured by system and mimics a decision tree. It runs something like:

-> Does this symptom exist (with a link to appropriate locations for
investigative purposes, each opening to new windows)?

-> A "Yes" answer links to another page, and a "No" links to a different
page. Each has the appropriate next step for that response or displays
the contact information for the appropriate Tier 2 support person. This
decision tree continues until the problem is resolved or the issue is
passed on to the Tier 2 person.

This approach limits the help desk operator's need to remember
everything, and also limits the complexity of wading through the entire
procedure on one page, especially when some symptoms are caused by
failures of other systems.

Maintaining the knowledge base is a hassle, with so many systems and
contacts. Requests keep coming in for instructions to be added, and all
additions require cross-linking to appropriate contact information,
investigative locations, other relevant system topics, and the
navigation system. With a limited number of HAT licenses, I am the only
available author.

I am trying to make the knowledge base more comprehensive, database
driven, and searchable by symptom. The HAT approach is quite restrictive
and creates a bottleneck at my desk. Another issue is that I have to
duplicate some topics because the symptoms they document exist in
multiple systems, and so the topics connect to multiple decision trees.
Some of the system development changes I see coming will only exacerbate
that problem.

To summarize, the HAT may be adequate, but it will require much more of
your time to maintain than will other options.

HTH,

Darrell Zuercher
Business Analyst
Tennessee Valley Authority

-----Original Message-----
From: techwr-l-bounces+dzuerche=tva -dot- gov -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+dzuerche=tva -dot- gov -at- lists -dot- techwr-l -dot- com] On Behalf
Of Brasel, Russell
Sent: Wednesday, December 27, 2006 9:24 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Advice needed for documentation project

I know I may have touched on this before, but my major project right now
is to create an on-line knowledge base for the developers of our new
database and programs. When I think of database documentation, I think
of something like Embarcadero Web Report-something that takes the db and
puts Entities, Attributes, definitions, relationships, etc. into a table
that appears as a webpage. My manager-who is out until after the New
Year-apparently expects something different, and expects me to use my
HAT to do it.

I personally think a wiki is a better solution, but I think that's going
to be a hard sell. But if I get sufficient feedback from the
developers, I can just update the online help system to do it. . .

Anyway, has anyone here done anything like this? And if you have, what
did you include in your documentation? Right now, all I'm doing is
taking our ER Web Report and setting up source documents in Doc-to-Help
to match-but it seems redundant.

Sorry I can't be more specific-my instructions are vague. Though I'm no
Michelangelo, I feel like I've been told, "Hey, Michel-that ceiling is
pretty bare. Why don't you do something with it?" (And yes, you can
make a Python reference to that. . . But please do it off list.)

Thanks for any advice you have,

RGBrasel
(Who would rather be at home reading his Christmas gift-the Foster 2
volume biography of W.B. Yeats.)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Create HTML or Microsoft Word content and convert to Help file formats
or
printed documentation. Features include single source authoring, team
authoring,
Web-based technology, and PDF output.
http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as dzuerche -at- tva -dot- gov -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/dzuerche%40tva.gov


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
http://www.techwr-l.com/techwhirl/ for more resources and info.

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

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

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. 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 admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Advice needed for documentation project: From: Brasel, Russell

Previous by Author: Re: Should we go to Structured FrameMaker
Previous by Thread: Advice needed for documentation project
Next by Thread: Trademark question


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


Sponsored Ads