Re: writing for programmers

Subject: Re: writing for programmers
From: "Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>
Date: Wed, 18 Nov 1998 15:45:45 -0800

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
sgallagher -at- expersoft -dot- com

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

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

Previous by Author: Re: Identifying Tables in Manuals
Next by Author: Re: How to Publish a Great User Manual
Previous by Thread: certification response
Next by Thread: Re: writing for programmers

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

Sponsored Ads