TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I normally lurk in the effluvial depths of the list, but I had to respond to
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++
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.
From: Lydia Wong [mailto:lydiaw -at- fpoint -dot- com]
Sent: Thursday, April 13, 2000 7:46 AM
Subject: RE: Writing for programmers
> 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
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
Best of luck!
Lydia : )
FarPoint Technologies, Inc.
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.