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:Re: Documentation Vs. Program Responsibility From:John McGhie <jmcghie -at- WORLD -dot- NET> Date:Fri, 18 Aug 1995 20:59:48 GMT
>William MacLeod (WBMACLE -at- ACCUSORT -dot- COM) asks whether software documentation
>should
>a) echo on-screen messages, and
>b) "reiterate things that are already somewhat user friendly in the
> program"
I vote "no" to both cases. I just removed 225 instances of this type
of information from a project.
- Most users have been using software long enough by now that they
are thoroughly familiar with the "normal" behaviour of a computer. If
it happens in their faces, they do not need to read about it.
- If it "doesn't" happen in their face, chances are they will ask
someone else before turning to the manual anyway.
- As an experienced user of software, I get intensely irritated by
having to flip 50 pages getting one sentence of useful information
(and two useless screen dumps) per page when a numbered list would do.
- Documenting program messages etcetera creates intense maintenance
hassles. I always miss updating one!
My contention is that the Windows "Getting Started" manual needs to
show every Action, Result, Effect for each step, but that the
documentation that we write does not.
Then again, I usually write for a technically sophisticated audience.
