I think you're missing the point here...
Engineers are generally bad writers. I may not have 15 years of
software engineering experience, but in the experience I've had in
working with reading the work of engineers, they generally don't have
the proper understanding of structuring and presenting a body of work.
This is particularly true when they can just Use the Source, Luke.
So I understand IRA's frustration when he comes upon documentation and
it is written in an idiosyncratic developer-centric manner that makes
assumptions that a newbie or even non-guru doesn't posses.
Allow me to submit an alternative, though. It's entirely possible to
screw the idea of getting a technical *writer* and instead get a good
technical *editor*. That person will be responsible for addressing
proper grammar, structure and presentation in order to ensure that the
documentation represents both the source and the technical writer's
intentions.
talli
On Jun 27, 2004, at 10:46 PM, Dossy wrote:
On 2004.06.27, IRA <[EMAIL PROTECTED]> wrote:
As an .adp developer, I *greatly* appreciate the effort going into
this
documentation effort.
Thanks.
I have to ask though---why can't we get a tech writer actually
assigned to the project?!?
We did. You're looking at 'em. :-)
We *have* actual tech writers in this company (unless we laid them all
off)---has anyone tried to get some of their time lately?
The problem with tech. writers in general is that they're not software
engineers. (I say the same thing about most QA people.)
Why is this a problem? Well, a lot of what's required to write good
tech. documentation is the ability to Use The Source, Luke (tm) and
then
distill the interesting or useful bits into literature. As stated
above
(tech writers != software engineers), this generally precludes them
from
using Jedi powers (i.e., using the source). (Hint: most orgs are so
talent-starved that when a tech writer CAN be a software engineer, they
usually end up there, leaving the tech writer pool with just liberal
arts types.) So, where does this leave us? With a bunch of tech
writers that have to lean on and take time from the already
under-resourced software engineering team, who have trouble finding the
time to write code, let alone talk to some tech writer who's going to
misinterpret details and write totally inaccurate documentation and
then
ascribe the poor software engineer's name who made the mistake of
trying
to learn 'em something strange.
Boy, that's an awfully cynical view of the world, but trust me: it's an
accurate description of my nearly 15 years of experience in the
software
biz. YMMV, of course.
If AOL has tech writers that can check out the AOLserver source, read
it, and write useful documentation for the ADP developer audience ... I
am ALL about getting a hold of some of that action and putting them to
use!
Care to introduce me to one of 'em?
-- Dossy
--
Dossy Shiobara mail: [EMAIL PROTECTED]
Panoptic Computer Network web: http://www.panoptic.com/
"He realized the fastest way to change is to laugh at your own
folly -- then you can let go and quickly move on." (p. 70)
--
AOLserver - http://www.aolserver.com/
To Remove yourself from this list, simply send an email to
<[EMAIL PROTECTED]> with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave the
Subject: field of your email blank.
--
AOLserver - http://www.aolserver.com/
To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of
your email blank.
