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.
Subject:Re: API documentation From:"Steven J. Owens" <puff -at- NETCOM -dot- COM> Date:Thu, 24 Jun 1999 13:18:59 -0700
> Dave Scott asked:
>
> > This may seem like a silly question, but how proficient in a programming
> > language (say, C++) should an employer expect of a tech writer who
> > produces API docs? And on the flip side, how proficient -should- you be?
>
> In my last job but one, I wrote API docs (for about 7 years) for C,
> Ada and C++ (you can guess it was defense). C++ gave me a lot
> of headaches at first since, working from source code, it was often
> very hard to determine what parts of an objects behavior was
> actually visible to the 'end user'.
Kelly & Pohl's _C by Dissection_ (an excellent book for intro C
programming) also has a section in each chapter discussing how the
concepts involved change in C++ programming, and an appendix with a
good summary of language constructs added in C++. Probably worth a
read if the poster above takes the job.
On the other hand, there's a heck of a lot more to coding OO than
just learning the syntax. And in any OO language, learning the class
libraries is tough row to hoe. So while you can quickly absorb enough
to be able to recognize what you're looking at, learning the mindset
and becoming familair with the class libraries will take a while. I
think that should be enough for documenting an API reference though.
However, you should work closely with some good programmers very
familiar with _the problem domain_ of the API (not necessarily the
folks who wrote the API, but somebody who'll be familiar with the
problems that will have to be solved with the API, as well as being
familiar with the API itself) to provide solid examples and commentary
about related API methods and classes.
Steven J. Owens
puff -at- netcom -dot- com
puff -at- guild -dot- net
