RE: SDK documentation

["Joe Malin" <jmalin -at- tuvox -dot- com>]

I've documented Java SDKs/APIs before, and I've worked with Javadoc.

Javadoc is a lot like your programmer's automated HTML file. It lists
the class hierarchy, and for each class/interface it lists
variables/constants and methods/attributes. Most engineers also offer
some simple documentation about the workings and limitations of the
class.

Java developers expect Javadoc for a class library/API/SDK. You really
have to have it, since among other things it automatically documents the
methods a class inherits from its superclasses.

So, at the least, you need a Javadoc equivalent which lists:
*class membership: which classes are in each library and what their name
is
*inheritance: the class hierarchy
*methods, properties, and constants: the available methods and their
signatures, the properties (public variables), and constants
*inheritance: what methods are inherited from the class hierarchy
*usage: basic use of each class and its method, and perhaps programming
examples or notes

In addition, you may want to document the SDK separately, as reference
information, but the "Javadoc" ought to suffice.

You need a programmer's guide that tells people how to install the API
and how to use any of the external tools that come with it. This is
mostly procedural information, and might cover how to use the API with
different platforms.

*You also need conceptual information!* This is *always* what is missing
or shortchanged with API documentation. You need to provide some sort of
conceptual framework that tells the developer *how* to use the API to
accomplish tasks. This includes conceptual overviews, examples, sample
code, and so forth.

In my experience, developers have a difficult time learning how to use
an API from the reference information alone. They may be able to do it,
but they'll have lots of questions.

The art and science of API documentation is in its infancy. I'm not
aware of any good reference sites, and if anyone has some, send them my
way too!




	 Joe Malin
Technical Writer
(408)625-1623
jmalin -at- tuvox -dot- com 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.	

-----Original Message-----
From: bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com
[mailto:bounce-techwr-l-216553 -at- lists -dot- techwr-l -dot- com] On Behalf Of Carrie
Baker
Sent: Thursday, July 28, 2005 5:47 AM
To: TECHWR-L
Subject: SDK documentation


For the first time I have to document an SDK (we normally write about
software GUIs).
The programmer is working in C++ and has created an html file that is
automatically generated, listing all of the classes and commands, what
they are comprised of and what they do. (I have checked the English).


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

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
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.