RE: Software engineer tech. writers? Do they exist?

Subject: RE: Software engineer tech. writers? Do they exist?
From: "Andrew Warren" <awarren -at- synaptics -dot- com>
To: "Dossy Shiobara" <dossy -at- panoptic -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 3 Sep 2007 03:57:38 -0700

Dossy Shiobara wrote:

> Are there software-oriented tech. writers who are also software
> engineers who can read through C source and write documentation
> based on what it does?

Sure, although the "Good, Fast, Cheap: Pick Two" rule applies
in spades... I suspect that it'll be hard to find someone who
knows enough C, Tcl, and SQL AND who has time for the project,
AND who's willing to work for a writer's wages rather than an

You know this already, else you'd be writing the documentation

> The C code in question (AOLserver) is very clean, well-written
> and organized.

That may be true, although as leader of the development team,
you're not in the best position to make that judgment
objectively. Just because it's clear to you or to Jim
Davidson doesn't mean it'll be clear to someone off the
street who hasn't contributed to AOLserver development.

Also, AOLserver's been under continuous development for,
what, 15 years? With the last eight or nine as a
collaborative open-source project? I haven't looked at the
source, but after that much development by so many authors,
I'd expect the codebase to have lost at least SOME of its
conceptual integrity... And this assumption's reinforced by
the fact that you want to document the software's operation
now, AFTER the code's been written, which suggests rather
strongly that the project hasn't had a strong spec.

Speaking of which... Who's your audience? It isn't clear
to me whether you're trying to create user docs or developer

If it's the former, are you SURE that the author would need
to figure out what the program does by reverse-engineering
the code? Wouldn't it be easier to just hire one of the
many AOLserver wizards out there and have him write what he
knows? He wouldn't have to be an excellent writer; I'm sure
there are LOTS of professional tech-writers with no AOLserver
or programming experience who nonetheless could turn his draft
into a readable final product.

Similarly for developer docs: Instead of making your author
laboriously slog through the code trying to understand it,
why not just let him or her ask the developers?

Actually, I'm not really sure why I'm even pretending that
reverse-engineering the code is even an option. The AOLserver
4.5 package has over two megabytes of C sourcecode, right?
NO ONE outside the development team can read and understand
that much code well enough to adequately document the program
that it represents.

> Is there any hope in finding a tech. writer who has the
> necessary skills to help document such a project, or am I
> just dreaming?

If I were you, I would really, REALLY plan for the docs to be
based on what your developers or expert users know, rather
than hope for someone to come in cold and just start writing.

Pro techwriters can be really good at interviewing subject-
matter experts; hire one who's already written documentation
for web servers or for SQL databases, and have your developers
and/or users talk to him or her. Personally, I think it'll be
a lot easier if your people write the initial drafts -- and by
the way, those drafts will probably be much more useful if you
let the techwriter give them some pointers before they start
writing -- but even if they don't do any writing, they HAVE to
at least talk to the writer. I don't think it'll be possible
any other way.



Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Software engineer tech. writers? Do they exist?: From: Dossy Shiobara

Previous by Author: Looking for 510k, DHF, CE Tech File Writers - Where can I find?
Next by Author: Need Experienced Advice re Accepting Foreign ELance Biz
Previous by Thread: Re: Software engineer tech. writers? Do they exist?
Next by Thread: RE: Software engineer tech. writers? Do they exist?

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

Sponsored Ads