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.
Those questions are all upside down, and are the source of what users
see as documentation that is difficult to use. You are ahead of
yourself, and need to back up and get a proper documentation plan. Start
instead with this question:
- For whom are you writing?
1. If you are writing for the beginning user, you should document only
the aspects he needs to get started properly.
2. If you are writing for advanced users, or for those driven by
curiousity, you might be creating a reference manual, and should
document many of the more complicated aspects. In general, a reference
manual should document everything. But see #3, below.
3. If you are writing for your own manager, and he's an insane
nit-picker who demands every aspect be thoroughly documented, only then
should you describe the totally obvious in detail. "Clicking the mouse
(see "Using the Mouse" in section 4.2.3.1.3) on the "Click here to quit"
button quits the application."
Reader #3 rarely reads the documentation, but merely notices its size
and its presence. That kind of documentation is rightly called
"shelfware". If the boss says it is too small, you could fluff it out
with a section of the Copenhagen telephone directory--perhaps the
listings for Jensen or for Larsen--and no one would notice.
I've not addressed the issue of "internals" documentation, in which you
interview the designers and developers to find out how they came up with
the requirements and the design. It's my impression that most outfits
rely solely on the developers' notes and the source-code comments
instead of creating official internals docs.
Raj wrote:
> The following are a few basic questions.
>
> Should all the fields in a screen be described in a procedure. Or, should only the fields that the user types an entry should be documented?
>
> Also, if the user searches for information, should all the information on that screen be documented, or only those headings that are not self explanatory be described?
>
> Can background processes be described in the procedure itself or as notes?
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
