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.
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
myself.
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 http://java.sun.com/j2se/javadoc/ 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
> To: TECHWR-L
> 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? http://www.iuniverse.com/media/techwr
---
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 http://www.raycomm.com/techwhirl/ for more resources and info.
