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:Help Desk Documentation Summary (long) From:Keith Anderson <kanderso -at- TRI -dot- COM> Date:Wed, 8 Jan 1997 17:32:54 -0500
Well, I guess it's time to take this subject to the list.
Originally I posted a message looking for technical writers with
experience in Help Desk documentation. My assignment is writing future
standards for all aspects of the Help Desk. Implementation could take up
to two years. I received numerous requests for a summary. I could not
respond to everyone individually and I apologize. Thanks for your input
and requests. If you do have more on this subject, please feel free to
Below is a summary of the responses I received:
1. Do you or your fellow writers have time to sit with the help desk and
listen to calls? I have found this to be very beneficial when one is
constructing help desk material. (Each environment is different and
dependent upon complexity of the software and knowledge of the user.)
What you might perceive as an important task may not be and vice versa.
Allocate 2 to 5 days. This amount of time should give you a good focus.
Philip J. Hellerman
Phil -dot- Hellerman -at- MCI -dot- Com
>2. Heh. More stuff than you can possibly imagine. Our experience setting
>up an intranet for what amounted to a Help desk for a large chip company
>in Silicon Valley was that the more information we collected and
>organized, the more they realized they needed. What they eventually
>committed to was an initial deployment of an intranet that had some
>information, but also had properly labelled "holes" into which they
>would put other information downstream. The fundamental idea was that
>this intranet was going to be dynamic, partially because it was
>accessible by everyone and thus subject to everyone's concept of what
>The lesson from this is that you've got yourself a long-term contract.
>Los Trancos Systems
etymes -at- lts -dot- com
>3. Design whatever you design with the fact in mind that very little is
>static. Your documentation will be "living" documentation. The first
>ever-changing factor on a help desk is technician turnover. Turnover is
>one of the few givens on a help desk. I'm thrilled to keep a tech for
>more than six months. Few people look for a help desk job as anything
>other than a stepping stone. Furthermore, in a large corporate shop, the
>help desk manager's job is one of the most stressful and least long-term.
> I figure there's a max one-year burnout cycle for the help desk
>manager--which leads to...
>The second ever-changing factor is that the desk procedures themselves
>always change. What do you do with a call when it comes in? How is
>client billed for time? How do help desk calls link to shipping and
>accounting? How much free support time does a client get? How do
>clients register their software? How do you bill internal profit centers
>for support time?
>Finally, the third ever-changing factor is the versions of the products
>the desk supports. If version 1.2a had a bug that caused to moon to drop
>out of the sky when you pressed the F4 key five times in a row,
>information concerning the bug must be available to the techs: cause,
>symptoms, related bugs and issues, workarounds, etc. If the 1.2b version
>of the software fixed this problem, you must keep the documentation
>concerning the 1.2a bug around (because not everyone will upgrade to
>version 1.2b), but you also must update the 1.2a bug info so that the
>tech will know that if he gets the client up to version 1.2b, the bug
>will go away.
>This is why your other reply suggested that you may be in for a long
>contract: you're never done. But if you're the type of person who likes
>to leave a good legacy long after the contract is complete, you're best
>off designing a system that allows for constant change, that is at the
>same time protected from the hazards of constant change, and that has
>easily duplicated change procedures for the people who come after you.
>Obviously, you need a dynamic tool to accommodate the dynamic nature of
>what you are documenting. I think HTML is your best bet. Reasons I say
> - HTML is easy to create (especially if it's for internal use and
>does not need to be fancy)
> - HTML is (by it's nature) perfect for the cross references and
>cascading procedures you'll need to
> - HTML is platform independent
> - HTML is easy to make available enterprise-wide and can be
>centrally updated on the fly without having
> to recompile anything or copy anything to anyone's C: drive
> - It's easy to convert existing docs to HTML; and, using
>something like Frame or Word, you can make
> one document and just use "save as," depending on what format
>you want: print or on-line
> - Later next year you'll be able to migrate all of your HTML docs
>to Microsoft's new "HTML Help"
> platform, which will make it easier to make your docs available
>to individual users on the Internet itself
> for your "Knowledge Base"; plus, with the HTML Help, you'll be
>able to compile all of your docs into
> "compressed HTML" and distribute them with the software itself
>on a disk or CD
> - With the HTML links, it will be easy to create multiple
>"paths" of links for a tech in training or for a more
>experienced tech; as a bonus (if I'm not mistaken), HTML Help will
>support Information Types so you
> can make different levels of information available to different
> - The HTML experience will look great on your resume
>You can download the HTML Help beta from microsoft.com. Also, I've been
>using the Internet Assistant for Word to create simple HTML docs.
>However, you might be better off with something like Frontpage, which
>will allow you to easily manage whole site maps.
>Good luck. Hope this helps.
>Simon Systems, Inc.
>danielread -at- juno -dot- com
>4. I would recommend capturing calls, keeping track where users are having
>problems, surveying technicians about where the weak spots in user
>knowledge, and compiling same into a "support" document. You can then
>go back to the original product documentation and beef it up where
>the users are having problems.
>The hardest part of writing user documentation is guessing what the
>user wants, where the problems may be, and how the user will use the
>product. The support technicians will become very familiar (probably
>very quickly) with where the user documentation will fall down.
>I would suggest a checklist form with some common areas of concern
>that the technician can check off during the conversation with the
>user. Maybe include some fill-in boxes for those problems that are
>not listed. Have the technician get specific details, if possible,
>about how the user got in trouble, and what was not understood. If
>this can be done on-line, the technician can quickly enter comments
>and notes that can be gathered and compiled for QC.
>Sr. Technical Writer
>alisa -dot- dean -at- mci -dot- com