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: Developer Documentation From:Jean Weber <jhweber -at- WHITSUNDAY -dot- NET -dot- AU> Date:Thu, 25 Mar 1999 15:02:02 +1000
At 12:10 PM 3/24/99 +0100, Chris Despopoulos wrote:
>I strongly advocate the engineers writing their own docs.
My perspective (and why I suggested editing the specs) comes from working
with teams of developers, many of whom speak English as a second or third
language. You mention "a Japanese engineer who's english was absolutely
unreadable ... But that was a very special case." That's who I work with
much of the time -- not Japanese, and not quite "unreadable" English, but
garbled or hard to sort out, particuarly by the other developers whose
native language isn't the same as the first developer's, none of whom write
English very well (but all of whom understand it). They usually welcome
assistance in turning their efforts into "proper" English, but they still
"own" the specs and are responsible for the completeness and accuracy of
the contents.
Interesting how one's experience colo(u)rs one's perspective on the best
(or most efficient) ways to do things <grin>.
>One part of
>the specification process should be review. That is the
>best place for you to be included in the development process,
I agree that's an excellent place in the cycle for a writer to be involved,
for the reasons Chris mentioned (not included in my excerpt here).
>it is a very good idea to have templates that include
>sections for every category that needs coverage.
A writer can contribute valuable input to the template, too, again for the
reasons Chris mentioned (not included here).
I figure that whatever makes my life (as a writer or editor) easier _and_
improves the product is a Good Thing. If getting involved in writing specs
has those positive results, I'm for it. If, for whatever reasons, it has
negative effects, I'd avoid it too.
