Re: API documentation

[Simon North <north -at- SYNOPSYS -dot- COM>]

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

I don't think proficiency -should- be a requirement, and I don't think
an employer has much choice in the matter anyway because the
number of writers with a level of proficiency are about as rare as the
proverbial rocking horse dung. Any proficiency is a bonus for the
(prospective) employer, but for the writer herself it's a nice extra. It
*is* nice to be able to spot the odd bug or too, but it shouldn't ever
get in the way of what you're really employed to do and, let's face
it, even if your an expert in the programming language in question
quite often that will still not be enough for you to be able to work
out what the code is supposed to do! My biased opinion would then
say, go for a basic familiarity and be happy with that -- at least it
helps when you including code in the documentation in that you
then know where and how to insert line breaks, logical page breaks
and additional comments.

Simon North


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