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:Simon North <north -at- SYNOPSYS -dot- COM> Date:Tue, 22 Jun 1999 15:27:50 +0200
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.