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.
Daniel Hall wrote:
>
> Somewhere in the doc, I have been asked to include some "general
> information" about troubleshooting.
>
> First question: What do I call this chapter?
>
> My ideas:
> General Information
> Troubleshooting Background
> Introduction to Troubleshooting
What you should call it is something that tells the user how and when to use
it. Is it something they should read before they do any troubleshooting? Then
how about "Read this first"? Or "What you need to know before you start."
'General information' is a horrible title. I can't imagine anyone wanting to
read something with that name. Who wants "general information"?
Your headings and labels should have a hook. The purpose of the hook is to
catch a specific user need. Users as a rule don't need "general information."
They need a specific answer to a specific question. What benefit will your
reader get from this chapter? THAT is what to call it.
It sounds like the problem really may be that you have a bunch of stuff left
over that you couldn't find a place for.
What does "Starting with the obvious" tell me? Nothing. It's a definite dud
of a title. I'd skip it in a flash. If something is so bloody "obvious", why
should I waste my time with it?
What do "Isolating problems," and "Saving system settings" have in common,
and why would I look for those topics in a chapter called "General
Information"? What is "general" about them?
Why is "Isolating problems", as you say, "narrative" rather than
"task-oriented"? I should think "How to Isolate a Problem" would be an
excellent task-based heading.
You say "Those who encounter something not covered in the manual can use this
section to attempt to solve the problem on their own." I certainly would not
get that meaning out of "General information" -- would you? Then how about
"Solving the problem on your own" for a title? Or "If you have a problem not
covered here"?
The best solution, really, is to take each piece of information and place it
where it will be found when needed. Stay away from boring, non-informative
headings like "Introduction" and "General information". Users -- especially
users who are under duress because things are falling over in a heap -- don't
have the time or the patience to go browsing around looking for things that
we haven't bothered to organize logically and label informatively.
