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: SDK/API documentation From:"David M. Brown" <dmbrown -at- BROWN-INC -dot- COM> Date:Wed, 21 Oct 1998 22:01:04 -0700
John--
An API is an application programming interface--the functions you can
call, the number and data types of any parameters to those calls, and
the number and data types of any values returned by those functions.
For an object-oriented language, the functions (called "methods") and
data structures associated with each object are encoded in the object's
definition. So, to an extent, the programmers are right--a level of
self-documentation does exist. Is it enough? Rarely, if ever.
An SDK is a software developer's kit--it may consist of absolutely
anything the distributor chooses to put in it: APIs, knowledge bases,
white papers, formal documentation, code editors, compilers, optimizers,
debuggers, ... absolutely anything.
Should you press for the inclusion of documentation with this product?
I'd at least point out the possible cost of omitting it: numerous tech
support calls, unhappy customers, and so on.
But, if your company charges for tech support and has a captive customer
base--or your customers are so familiar with the product that they're
practically part of the development team--these points may not carry
much weight.
Are programmers really necessary? Only if you want to sell software.
:)
--David
==============================
David M. Brown -- Brown Inc.
dmbrown -at- brown-inc -dot- com http://www.brown-inc.com/
==============================
See our web site for news about HTML Indexer, the easiest way to
create and maintain indexes for web sites and other HTML documents.
