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: Writing API Guides From:Chris Knight <knight -at- ADA -dot- COM> Date:Fri, 24 Apr 1998 11:20:21 -0700
Learning the language your API is written for is a must, but not beyond
an "intoductory course" level. You need to know enough syntax to check
that any code you include (typically function declarations, with
comments on each formal parameter and each value returned) is correct.
You also need to know about data structures.
With object-oriented languages (like Java or C++) you need to know about
classes and methods.
But you also need to know more than most tech writers about linking.
Users love "See Also" sections. Here you need sufficient knowledge of
what the customer is going to be building with the API. Domain knowledge
is, as always, a requirement.
Find some good examples to study. Ask your "target" readers for manuals
they found usable and useful.
Do your user-requirements analysis, plan carefully, and make sure
the document gets read by several reviewers. This stuff is deadly to
read; errors can slip by easily. Get an outside proof-reader.
Hope that helps.
--
Chris Knight
Consultant, Technical Communication Architect
Vancouver BC, Canada
(currently at Applied Digital Access,
E-mail: knight -at- bcg -dot- ada -dot- com Phone: 604-415-5886 Fax: 604-415-5900)
Opinions expressed are my own, not ADA's
