Re: Documenting software

[Lydia Wong <lydiaw -at- FPOINT -dot- COM>]

Sometimes we writers where I work find it helpful to think of ourselves as
filters. Often, a programmer will give us a "brain dump" of everything
he/she knows about the software and all it's underlying stuff (which can go
*way* over our heads, sometimes). However, we try to ask ourselves, "Does
the user REALLY need to know that?"

Depending on the developer, the software, and the users, they might not need
to know any of it. Sometimes they do need to know some of it, but in English
and in a very summary way.

So, in case it's helpful, whenever a developer starts going on about
underlying window messages and if-then loops and memory leaks, my mind sends
up a little flag that says, "what part of this do I need to know and
communicate to the users?" That makes me feel less panicked and not quite so
bad when I don't understand half of what the developer is saying. (Sometimes
that's okay!)

Lydia Wong
Technical Writer
FarPoint Technologies, Inc.
www.fpoint.com

-----Original Message-----
From: Katherin King <kking -at- BROOKTROUT -dot- COM>
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
Date: Tuesday, June 30, 1998 3:53 p.m.
Subject: Documenting software


>For those of you who document software applications, how much of what
>you do is documenting the GUI and how much of it is documenting the
>underlying structure, the means by which the GUI is implemented? In
>other words, how important is it, do you think, for tech writers to
>understand the inner workings of the software?
>
>Kathy Stanzler
>Technical Writer
>Brooktrout Technology Inc.
>Southborough, MA
>(508) 786-9182
>kking -at- brooktrout -dot- com
>
>
>