Re: writing for programmers

[Svi Ben-Elya <svi -at- ELIASHIM -dot- CO -dot- IL>]

I have found that writing from the top down always works. Begin with why the
user (programmer) buys the product, i.e., what does it do. Next, what is the
concept behind how it works.

For example: The program takes large chunks of information and breaks it
into smaller pieces and creates a map. The map and the smaller chunks are
sent over standard telephone wires and reassembled at the other end.

At this point you may not have written anything that the programmer can use
to write or modify the program. However, you can begin to organize
information. In the above example, you must describe the following:

Large chunks of information

Small chunks of information

The map used

How the small chunks are transmitted and received

Each of these may be broken down further until you reach the level of
command structure, commands, procedures, etc. The process of working from
the top down gives you a better understanding of the product and enables you
to provide a succinct overview. The technical aspects then become easy. You
simply copy what the programmers write, possibly add short descriptions of
what they tell you each command/structure/procedure does, and have them
proof your work.

This method requires you to spend a large amount of time on the most basic
and simple aspects of the product. The so called, stupid questions about
things that "every programmer already knows" are usually the most important.
The rough equivalent of the wheel. Once we understand the concept of the
wheel, inventing methods of transportation is relatively easy even though
"higher levels of technology" are used in carriages, cars, trains, etc.
_______________________
- Svi Ben-Elya -
svi -at- il -dot- esafe -dot- com
chase -at- netvision -dot- net -dot- il
_______________________



-----Original Message-----
From: Technical Writers List; for all Technical Communication issues
[mailto:TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU]On Behalf Of Susan W. Gallagher
Sent: Thursday, November 19, 1998 01:46
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: Re: writing for programmers


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=


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