Re: Writing for programmers (previously untitled)

[Elna Tymes <etymes -at- LTS -dot- COM>]

> Martin:

> Has anyone tried rewriting a document written by programmers (in programmer
> speak) for programmers before?

Wait a minute. I've written dozens of manuals for programmers, but I've been
able, in each case, to avoid programmer-speak.  I hope my experience is what
you're looking for.

IMHO, programmers need clear, concise, technically accurate language just as
much as a non-programmer audience.  With a progammer audience, however, you can
afford to skip explaining some more technical concepts, such as swapping and
memory allocation and communications protocols and stuff like that.  Although
there are some programmer audiences where you DO have to describe that stuff.

> The existing document I have been given is currently described as a user
> guide but I am wondering if you can write a general user guide for such a
> specific audience. Would a general reference guide be more appropriate - but
> if this is the case then how do you reword anything if you dont have the
> technical knowledge as a writer to redwrite the text.

You can call it a user guide if you define the user as a progammer up front.
I've seen plenty of manuals entitled "User Guide" that were directed at a
programmer audience.  User Guides tend to be written in a style that leads one
through the process of using whatever the tool happens to be. Reference Manuals
tend to be more like dictionaries or almanacs or things where you know the user
won't be reading it through from front to back, merely turning to the section of
particular interest.

You don't need technical knowledge to write a book for programmers, although
sometimes that helps.  For instance, if you write a book about a programming
language, you'll need to learn how to create programs in that language as you
write, mostly for the examples you'll have to provide.  However in most cases
you'll probably have someone who already IS a programmer to help you through
places that seem overwhelmingly technical.

Let me give you an example.  I happen to know Java, and because of that I was
picked last spring to help write a series of manuals about a new operating
system based on Java.  I certainly didn't know the operating system going in,
and it took a fair amount of study to come to terms with the layers and
interfaces that were basic to this operating system.  My team's job was to take
existing specs and write several manuals that explained this very complex
operating system to programmers and managers who were looking 'under the hood.'
My knkowledge of Java was certainly not at the level of my audience, but I knew
enough to be able to understand the concepts behind the operating system, and
how the Java language could implement them.  And I grabbed a nearby programmer
when I needed further explanation. The manuals are now released and are quite
readable, even by non-programmers.

What I've found in trying to define a "programmer audience" is that everyone
appreciates simple, clear prose and sufficient illustrations and good layout.
I've also found that even the most technical programmers work well with clear
language and clean logic, and that attempts to write in 'programmer-ese' is
usually someone's attempt to obfuscate what really should be stated clearly.  If
you doubt this, go to some technical bookstore and pick up any of the UNIX
books, or some of the more technical NT manuals.  I think you'll find that most
of these published books use simple, clear language too.

Don't let yourself feel overwhelmed by this project - remember that most users
start out in a state of confusion too, and that you can use your own experience
to their advantage.

Elna Tymes
Los Trancos Systems


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