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.
Sue writes
... To some, each individual method
is an API (eww, I hate this one) and SDK never even enters
the vocabulary. This "documentation magically turns an API
into an SDK" definition is a new one on me, but that doesn't
mean it isn't valid *somewhere*. <g>
Whether it's called an API or an SDK, the task is essentially
the same -- helping the user-dev integrate the supplied
code into an application.
...
People do throw terms around, but ask a programmer. As someone said in this
thread, documenting API's is great because you can talk to your audience and
ask them what they like and don't like. So...
SDK is a kit. Kit is in the name. A kit is essentially productizing an API
set. That usually means code (binaries or source), installers, tools, and
docs. The docs are the most challenging and most important. Unless the API
is trivial and source code is provided, then the docs are the only piece of
the SDK that explains to an engineer how to build software using the
provided tools and API's.
Sparse SDK's may contain few or no tools and just point you at gnu or some
other standard software development toolset. Robust SDK's will include IDE's
with compilers and debuggers, etc.
Usually, all SDK's include a document on the available API's to the
programmer. Sparse SDK's will include only reference manuals. Robust SDK's
will include programmer guides (ht write apps/plug-ins/etc.) and maybe even
tutorials with sample code, etc.
An API is an interface. This means that a method/function/call is an API.
Generally, the whole package/library of methods/functions are called an API,
but sometimes they are referred to as API's (plural). Choose one or the
other and stick to it. The choice will not confuse a programmer. Switching
between the choices will confuse the programmer. To make some matters
worse, there could be multiple sets of API's in a single SDK. For example,
my staff is currently documenting an interface that allows programmers to
directly call the OS, a C-language middleware, and a set of flash calls. I
would refer to these as three distinct API sets in a single SDK. O boy.
This probably doesn't make things clearer, but I return to the beginning...
Ask your programmers.
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
