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'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
