Re: Developer Documentation

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.

Cheers, Jean
Jean Hollis Weber
The Technical Editors' Eyrie
mailto:jhweber -at- whitsunday -dot- net -dot- au

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Developer Documentation
Next by Author: Technical Editors' Newsletter launched
Previous by Thread: Re: Developer Documentation
Next by Thread: Getting information

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads