Re: writing for programmers

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

At 02:24 PM 11/18/98 +1100, you wrote:
>Is anyone out there?
>Has anyone tried rewriting a document written by programmers (in programmer
>speak) for programmers before?

Oh, yes -- and my first was also written by a german native. It was
written in passive/agressive voice and excerpts won the first CoreComm
Worst Documentation contest! (the now-famous "Type the field name Name
in the Field Name field.") <nostalgic sigh>

Not only was it poorly written, it wasn't the least bit organized --
logically or otherwise. When it came time to re-write the doc set, we
started from scratch.

It certainly is possible to write a user guide for a programming tool.
In some cases, it's positively vital. You wouldn't try to learn how
to use photoshop with just a list of dialog boxes to help you, now,
would you??? <g>

And yes, when you don't know the language, putting the manuals together
sometimes seems akin to assembling a jigsaw puzzle blindfolded with
nothing but a pair of scissors to help you -- but you're also at an
advantage in that if you get to the point where *you* understand it,
any programmer is bound to find it perfectly clear. Don't let the
technology scare you and don't be afraid to ask "dumb" questions.
;-)

Sharpen your interviewing skills and bang out a good, solid outline
before you begin. Interview your SME at your keyboard and keep asking
"then what?" -- then watch the amazement on your SME's face as the
outline takes shape. What you'll probably find in the current version
is a whole lot of how the system works and not a whole lot of how to
use it.

Best of luck!

-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com     http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams


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