Re: API documentation

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

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: Should I Bill for Time Reading?
Next by Author: Why you didn't get the job
Previous by Thread: API documentation
Next by Thread: ADMIN: Responsibilities Reminder


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


Sponsored Ads