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.
It seems to me that most software manuals overemphasize the step-by-step
information at the expense of the information that would let the user know
how the whole thing works. If the user can understand the program as a
whole, he or she will not need step-by-step instructions all the time. This
can save a lot of words: many programs allow a lot of combinations of
actions, and to describe each combination can make a very thick manual (and
often does).
An organization I often use is the following:
Chapter 1: What it is and why you should use it. What it will do and not
do. (The kind of information you might give to someone who was deciding
whether to use this product).
Chapter 2: How it works (in functional terms, not software internals) -
information that the user must have to use the program. How information
gets in and out, how it relates to other products, where it ends and others
begin. How it is used in general. How menus relate to each other, with
perhaps a general flow diagram. General rules for users entering data, if
any.
Chapter 3: Routine Operations. How to do the things that users do all the
time
Chapter 4: Advanced Operations. How to do the things that are rare or
advanced.
Chapter 5: Troubleshooting
Chapter 6: Technical reference information if required
In the above, the reader should have good idea of what is going on by the
end of chapter 2, and so need a lot less information in chapter 3. Chapters
1 and 2 are harder to write of course: step-by-step information is easier
to write although it can be tedious.
I hope this helps with your question. I would like to see other suggestions
for the high-level organization of a manual.
Regards
John
Original Message-----
>>>From: Melonie Holliman [mailto:melonie -dot- holliman -at- TXEXMTA4 -dot- AMD -dot- COM]
>>>Sent: Tuesday, April 06, 1999 10:01 AM
>>>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>>>Subject: Software Manual Organization
>>>
>>>
>>>Howdy,
>>>
>>>I am reorganizing a software manual and the process has
>>>brought up an issue for me. Each manual I have worked on
>>>has had three types of info a user would need: an explanation
>>>of each menu and its items, how tos, and theoretical or
>>>historical information. In the last manual I wrote, it was easy
>>>to mix all three. In this current manual, the how tos tend to
>>>use more than one menu in each process so I have set
>>>them into another chapter. Right now, I trying to decide if
>>>I should merge the theoretical with the menu explanations
>>>or if that would be too confusing.
>>>
>>>To those who write software manuals, how do you tend to
>>>organize it (considering the types of information I presented
>>>above)?
>>>
>>>Melonie R. Holliman
>>>Technical Writer
>>>CPD Marketing
>>>Advanced Micro Devices
