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: Documenting a C++ API From:Geoff Bradbury <bradg -at- INTEXT -dot- CPSG -dot- COM -dot- AU> Date:Fri, 22 Sep 1995 10:08:45 +1000
At 15:49 21/09/95 -0400, you wrote:
>From: Kim Ferri x710 <kim -at- ASPECTDV -dot- COM>
>>Our product includes a C++ API that enables customers to build their own
>> applications using the core functionality of our product.
>>Has anyone out there documented a similar C++ API?
>>Do you have any advice in terms of organization, detail, examples, etc?
[snip]
____________________________________________________________
At 9:41 22/09/95, I wrote:
Greetings Kim...
I handle the documentation for the APIs developed by our software engineers.
The APIs are a part of the Software Development Kits we market. Most are in
standard C rather than C++, but the same ideas still apply (with a little
tweaking).
Each SDK comes with a single Programmer's Guide. One and one only
publication. There were times in the not-so-distant past where one product
could have several publications: not a good look and a mongrel to maintain!
The basic structure I use for Programmer's Guides goes like this:
* Preface - introductory blurb, publication conventions, publication
roadmap, technical assistance info, etc.
* Ch 1 - Understanding the API - the conceptual material, examples of
the API in action, etc.
* Ch 2 - Getting Started - system requirements, API file manifest,
installation instructions (we support Windows and various flavours of unix
platforms), general hints and tips on using the API, compiling and linking
hints and tips, details of the example program we supply as part of the SDK.
* Ch 3 - API Function Summary - provides a thumbnail sketch of each
API call, categorized by functionality. For example, output syntax
specification category, initialization category, etc.
* Ch 4 - API Function Reference - similar structure to ch 3, using a
detailed call layout: function type, parameter types and descriptions,
callback function descriptions, return values, comments, code examples.
* Ch 5 onwards - API-specific material. Some APIs require only a
single chapter, others need several to describe functional areas.
* App A - Operating Limits - Just how far you can push this little
puppy...
* App B - Return Values Reference
* Glossary
* Index
Following this structure and associated page layout standard has resulted in
a growing set of publications that explain each API. I'm still going! More work!
Hope this is of some assistance.
...cheers!
__________________________________________________
Geoff Bradbury - Technical Writer for InTEXT Systems
"Makers of extraordinarily fine text storage and retrieval software"
PO Box 310, Deakin West, ACT 2600, Australia
+61 6 283 6804 (voice) +61 6 285 4316 (fax)
My writings reflect my views: not those of InTEXT Systems
"I love deadlines. I like the whooshing sound they make as they fly by."
- Douglas Adams
__________________________________________________
