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

["Andrew Warren" <awarren -at- synaptics -dot- com>]

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
    engineer's.

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

> 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
    docs.

    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.

    -Andrew

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
http://www.DocToHelp.com/TechwrlList

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

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.