RE: Technical Writers Needed for API Doc: Really?

Subject: RE: Technical Writers Needed for API Doc: Really?
From: "Darren Barefoot" <darren -dot- barefoot -at- capeclear -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 11 Jan 2002 11:54:52 -0000

Good question...For APIs, I've ranged from writing them from scratch to
being ProofReadingBoy. In the former case, I was heavily assisted by the
development team. That is, I made a first pass at those elements
(methods, variables, classes, etc) that I could figure out, and then
consulted with the developers for the rest. I couldn't have written it

In my limited experience, you need to not only speak the programming
language that the code is in, but you have to have a pretty decent grasp
on what each component does. Furthermore, a lot of APIs seem pretty
"down and dirty" to me, and so their users don't necessarily expect the
same level of professionalism as they might from end-user documentation.
In short, while APIs are usually a collaborative effort, and I think
it's a rare writer (or a lot of highly-commented code) that has the time
and knowledge to write an entire API on his or her own.

As a side note, Sun has created a relatively unsung but very nifty tool
called Javadoc which generates API documentation in HTML format. Of
course, it only works if you're programming in Java. The home page for
Javadoc is at and it has this to say
on the product:

"Javadoc is a tool that parses the declarations and documentation
comments in a set of source files and produces a set of HTML pages
describing the classes, inner classes, interfaces, constructors,
methods, and fields."

Hope that helps. Thanks. DB.

> -----Original Message-----
> From: bounce-techwr-l-65243 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-65243 -at- lists -dot- raycomm -dot- com] On Behalf Of
> Cedric Simard
> Sent: 11 January 2002 10:18
> Subject: Technical Writers Needed for API Doc: Really?
> Still, they think it would be too expensive to train a
> technical writer so
> that he/she can become independent enough to document APIs.
> The result is
> they would not even let any chance to this idea. The only
> thing they agree
> with is that the technical writer can proofread the
> documentation to put it
> in proper English.
> I do not like the idea of tech writer being only a proofreader. The
> technical writer can also bring his/her skills on
> documentation structure
> and information management. Still, I have to admit I'm still
> wondering if
> all those CTOs and developers are not right, after all?

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for?

Have you looked at the new content on TECHWR-L lately?
See and check it out.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Technical Writers Needed for API Doc: Really?: From: Cedric Simard

Previous by Author: RE: Business issues, documentation and editors
Next by Author: RE: Alternatives to MS Project/Project Central
Previous by Thread: Technical Writers Needed for API Doc: Really?
Next by Thread: RE: Technical Writers Needed for API Doc: Really?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads