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: Other kinds of technical writing From:Ginna Watts <gwatts -at- QUESTERCORP -dot- COM> Date:Mon, 26 Oct 1998 11:47:16 -0800
Ben Kovitz wrote:
>
>Well, let me rephrase the question, then. Should system analysts,
>programmers, engineers, etc. be expected to write internal technical
>documents of reasonable quality, or is this kind of writing best treated as
>a specialized skill, requiring specialized training or talent that you
>shouldn't expect of a programmer? Should you hire a separate person to do
>this job for the engineers, treating the engineers as SMEs, or should the
>engineers normally do it themselves? What's the best division of labor?
>
>Or in other words, is expecting programmers to write good technical
>documentation the same fallacy as expecting programmers to design good user
>interfaces?
In our company, for each external project we must produce the usual suite of
IEEE conforming documents: requirements specifications, design descriptions,
plans of all shape and form, and of course, system functional descriptions.
I have tried to ease the process by creating extremely detailed templates to
guide the engineers. (In my experience, engineers write everything they know
about a product/box/software item in one location, then hand it back to
me...but they're getting better.) In my role as editor/writer, I tend to
move things around a lot. For example, in our current project I got good
info on error messages and memory usage....in the requirements
specification. I know enough to move it along to the design document, clean
it up, check it for consistency, and then 'pretty it up'.
Programmers, engineers and analysts should know enough to make a significant
'first pass' at such documents, but there should also be a separate person
guiding the whole process. (I also manage to catch technical errors - "Joe,
in your software document you say the system produces output X. But Jane's
hardware document says that she gets output Y from you. Which is correct?")
I know for a fact that I'm the only person in our organization who has ever
read any of the IEEE document specs, and everybody here likes it that way.
Ginna Watts, Technical Writer
Quester Tangent Corporation
Sidney, BC
gwatts -at- questercorp -dot- com
