Re: Writing API Guides

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

Previous by Author: Re: WP to Word
Next by Author: Re: graphics size in Word files
Previous by Thread: Re: WP to Word
Next by Thread: Professionalism: "excellence in the face of ignorance"

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

Sponsored Ads