writing an SDK

[A***@toyota.com]

Follow this thread:

http://ask.slashdot.org/article.pl?sid=05/03/21/1651241&tid=156&tid=4



Thanks!

---Amanda

Amanda Abelove
Technical Writer, [phone]
***@toyota.com
***@abelove.com
Cell: 310-430-0049


__________________



I'm starting a new job. The first thing they want me to write is an
SDK. I've never written one. I don't even know what they look like,
even though I've been documenting software for years. Most of my work
has been in support of GUIs and CLIs, but I've never been assigned an
SDK or an API. Any suggestions where to start? Thanks.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Susan W. Gallagher]

Actually, APIs and SDKs don't look like much of anything.
You've just become the UI. <g>

Start by reading "Yesterday API was just another acronym;
today I have to document one!" at this link:

http://members.cox.net/susanwg/susanwg/api.html

(There's also a paper on OO terms and technolgy there if
you need it.)

Read a book or take a class to learn the programming language
that you need to document. If it's C++ or Java, there are
free good books available at www.bruceeckle.com

Join the nettechwriters group on Yahoo.

Welcome to the club! Good luck!
-Sue Gallagher

|
| From: Siliconwriter <***@comcast.net>
| Date: 2005/04/11 Mon PM 07:02:10 EDT
| To: "TECHWR-L" <techwr-***@lists.techwr-l.com>
| Subject: writing an SDK
|
|
| I'm starting a new job. The first thing they want me to write is an
| SDK. I've never written one. I don't even know what they look like,
| even though I've been documenting software for years. Most of my work
| has been in support of GUIs and CLIs, but I've never been assigned an
| SDK or an API. Any suggestions where to start? Thanks.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Sean Hower]

--------------------------------
Susan W. Gallagher suggested that Siliconwriter should check out this article:
http://members.cox.net/susanwg/susanwg/api.html
--------------------------------

Susan's article is an _excellent_ resource for getting started. It scores many cool points in my opinion. :-)

Bruce Eckel's stuff is at http://mindview.net/Books These too are excellent resources. The first couple of chapters of Thinking in C++ will help you understand OOP.

If you're writing an SDK you should ask your boss if you can get the IDE that your developers use installed on your machine. That should come with its own SDK and you can use that as a model.

If you're company is using .NET, you might look into NDoc (http://ndoc.sourceforge.net/) if you are ever asked to produce an API.

********************************************
Sean Hower - tech writer
http://hokum.freehomepage.com


_____________________________________________________________
Create your own web site for FREE at http://www.freehomepage.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Dana Worley]

On Monday, April 11, 2005, Siliconwriter wrote:

| The first thing they want me to write is an SDK. I've never written
| one. I don't even know what they look like,

I hope they are asking you to *document* an SDK, not write one. An
SDK is a "software development kit" and it is usually a bunch of
code modules that a third party can use to develop customized
software.

If they are asking you to *write an SDK* you may have taken the
wrong job!

Dana W.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[James Jones]

Gordon & Gordon used to have what looked like a useful offline (where
you get all the stuff and complete the course on your own) course on
documenting APIs and SDKs. Maybe they sell a comprehensive version of
their courses, but maybe they still offer individual parts.

NOTE: I have no connection to them.

Jim Jones http://www.tinyurl.com/4arjc

| ...they want me to write is an SDK. I've never written
| one. I don't even know what they look like...

I hope they are asking you to *document* an SDK, not write one...



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Chris Gooch]

| I hope they are asking you to *document* an SDK, not write one.

An SDK is an API with docs, so I guess in a sense if you write
docs for an API then you turn it into an SDK...


Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com













^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Guy K. Haas]

Chris Gooch wrote:

| An SDK is an API with docs, so I guess in a sense if you write
| docs for an API then you turn it into an SDK...

An SDK is more than an API with docs. I was going to muster a set of
URLs from my favorite online resources, but there's a better way.

Go to Google and ask it
define: sdk

and it will give you a heap of links to definitions that basically agree
that an SDK (Software Developers/Development Kit) is code (typically one
or more APIs) plus tools (such as an Integrated Development Environment)
plus documentation.

--Guy K. Haas
Software Exegete in Silicon Valley


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Bill Swallow]

No, your statement that "an SDK is an API with docs" is completely incorrect.

There is a big difference between a SDK (software development kit) and
an API (application programming interface). The former allows you to
develop applications. The latter allows you to leverage third party
functionality via function calls into a 3rd party component from
within the application you're developing. The two are very, very
different.


On Apr 12, 2005 12:36 PM, Chris Gooch <***@lightworkdesign.com> wrote:
| > I hope they are asking you to *document* an SDK, not write one.
|
| An SDK is an API with docs, so I guess in a sense if you write
| docs for an API then you turn it into an SDK...

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Chris Gooch]

Well I took a bit of a kicking there didn't I?

Guy wrote:

| Go to Google and ask it
| define: sdk

Hmm... ok

from http://www.webopedia.com/TERM/S/SDK.html

++
SDK: Short for software development kit, a programming package that enables
a programmer to develop applications for a specific platform. Typically an
SDK includes one or more APIs, programming tools, and documentation.
++

Or then of course somone mentioned Gordon & Gordon's
course on writing API docs, here's a quick summary they
did for the STC:

http://www.stc-israel.org.il/archive/gordon_api_sdk.htm

++
Question: What is the difference between an application programming
interface and a software development kit?
Answer: Documentation, mostly.
++

Bill said:

| No, your statement that "an SDK is an API with docs" is completely
incorrect.
|
| There is a big difference between a SDK (software development kit) and
| an API (application programming interface). The former allows you to
| develop applications. The latter allows you to leverage third party
| functionality via function calls into a 3rd party component from
| within the application you're developing. The two are very, very
| different.

Look, I don't want to be all defensive, but this is misleading. You develop
applications by making calls to third party libraries; e.g., WIndows,
LightWorks,
OpenGL, etc. Whether they are "third party" or related to the operating
system
is not relevant to whether something is an API or an SDK. Likewise there's
no reason why a compiler or IDE that a programmer uses has to be supplied
by the same people as the operating system, hardware, or multiple third
party
APIs. An SDK is _not_ the same as a programming environment / compiler /
IDE. Which is not to say that an SDK wouldn't have to include some
compilation tools if it were not compiled as a set of libraries that can
be linked to directly on the developer's intended platform (which I think is
what Susan Gallaghers piece is trying to say).

I think there are enough angels on this particular pin now.

Chris.

Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Bill Swallow]

| Look, I don't want to be all defensive, but this is misleading. You develop
| applications by making calls to third party libraries; e.g., WIndows,
| LightWorks,
| OpenGL, etc. Whether they are "third party" or related to the operating
| system
| is not relevant to whether something is an API or an SDK.

That wasn't my point. An API is a subset of functions that support
integration of a 3rd party component into an application. Developers
use the API in addition to whatever SDK they are using to create an
application. You cannot write a complete application with just an API.
A SDK can contain APIs and provides a more complete library of "stuff"
for developers to use in developing a working application.

| Likewise there's
| no reason why a compiler or IDE that a programmer uses has to be supplied
| by the same people as the operating system, hardware, or multiple third
| party APIs.

SDKs do not need to include the IDE. I can use the .NET Framework SDK
in VS.NET or in Borland, for example.

| An SDK is _not_ the same as a programming environment / compiler /
| IDE. Which is not to say that an SDK wouldn't have to include some
| compilation tools if it were not compiled as a set of libraries that can
| be linked to directly on the developer's intended platform (which I think is
| what Susan Gallaghers piece is trying to say).
|
| I think there are enough angels on this particular pin now.

Was someone stating SDK = IDE?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Susan W. Gallagher]

I've worked in a lot of companies that sold code.
To some, an API was developed "ready to use" and an SDK had
to be compiled on the user-dev's machine. To some, an SDK
was specifically meant to extend another commercial application
(like an SDK for Word so you could develop RoboHelp) and
everything else was an API. 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.

A rose by any other name... and all that.

-Sue Gallagher



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

[Walden Miller]

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.

walden




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
techwr-***@gts.org
To unsubscribe send a blank email to leave-techwr-l-***@lists.techwr-l.com
Send administrative questions to ***@techwr-l.com. Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.