RE: Writing for programmers

["Kinsky, John" <jkinsky -at- filenet -dot- com>]

I normally lurk in the effluvial depths of the list, but I had to respond to
this thread.

I agree with both Lydia and Michael. There is no substitute for learning how
to handle the programming language with skill, but acquiring programming
skill does not mean you have to become a developer.

I have been writing documentation for complex APIs for slightly over two and
a half years. In that time, I have had to learn - at least in part - C++
syntax and logic, Visual Basic, VBScript, JavaScript (ECMA), XML, and ASP
architecture just to produce useable sample code. I do not consider myself
to be a developer. I'm a writer, and I want to continue being a writer.

Learning what other writers did to make the similar material comprehensible
is only a small part of the making this particular type of documentation
work. This is not procedural documentation, and the level of abstraction
needed to connect the domains what can be done and why a developer should do
something a certain way is incredibly challenging.

Build a rapport with sympathetic developers. They are probably your best
resource in any project. Reference materials and books on programming
techniques are fine, as far as they go, but I have found that most of the
products I document more often deal with the exception rather than the rule
where programming is concerned.

In addition, you must develop two daily disciplines: (1) breath deeply every
morning before digging into the work. (2) Smile; it unnerves people.

John Kinsky


-----Original Message-----
From: Lydia Wong [mailto:lydiaw -at- fpoint -dot- com]
Sent: Thursday, April 13, 2000 7:46 AM
To: TECHWR-L
Subject: RE: Writing for programmers


Shelley asks:

> I've recently started a new job in which I am documenting software for
> programmers. It's Java with SQL Server at the back end. I don't
> really know anything about this stuff and would really enjoy a focused
> discussion among those of you who might be documenting for a programming
audience.

Shelley, you are going to have to learn about "this stuff." There's no way
around that if you're going to document it. Will you have to become a
programmer? No. But you are going to have to learn about what they do, why
they do it, and the basics of the language they are using.

You are right to try to get some good books. Besides looking for books about
writing about "this stuff," you should get books on programming. Start with
the "Dummies" books on Java and SQL and go from there. And, as Mike West
suggests, seek out sympathetic developers. They can clue you in on what's
important to know about your product.

Also, search the TechWr-L archives. There was a discussion about documenting
programming languages back in December of 1999. I saved a lot of those
posts, because they had good advice. I know there have been other good
discussions in the past. (Look for posts from Michael Wing--I remember he
had some excellent advice on this topic.)

Don't forget to look at your competitions' docs. Some of their writers might
be quite knowledgeable, and you can learn from them what needs to be covered
in your documents. Of course, don't plagiarize, but do look closely at their
content and style.

Finally, if you'd like to see some samples of our documentation, you can
download trial versions of our products from our web site (www.fpoint.com).
If you install the trial versions, our online help files will be installed,
and those contain the majority of our documentation for each product. At
least it might give you some ideas; though our products are different (we
create ActiveX/VBX/DLL controls for Windows developers), our audiences are
similar.

Best of luck!

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


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot- 

Sponsored by IEEE Professional Communication Society. Meet PCS
members and officers in Booth 304 during exhibit hours at the STC
Conference, May 21-23. Learn more about us at http://www.ieeepcs.org.

---
You are currently subscribed to techwr-l as: jkinsky -at- filenet -dot- com
To unsubscribe send a blank email to leave-techwr-l-30398I -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.