HOWTO Document and Write an SDK?

jmwmit asks: "A startup that I am working with is looking to write its first SDKs - one public for community developers and one for 3rd party commercial developers. What is the Slashdot recommended or preferred format for SDK documentation, both the code APIs and the general docs? What great SDK examples have people used in the past and would recommend as good models? What do Slashdot developers consider absolutely necessary features in an SDK, regardless of the application?"

Comments

Think about it

[l0rd]

Just think long and hard when you design it. There's nothing annoying than having to overhaul your code becuase a function/class syntax has been changed.

What helps me

[secondsun]

What makes a good SDK is decent documentation and design. What makes an excellent SDK is well though out designs and very detailed documentation. Code examples, comments, descriptions of functions functions, parameters, and return values.

Sun has done a wonderful job with java and documentation. The only thing that I would like to see added to it would be links to items that reference each function/object.

A project that has done an awful job at documentation and design is Squeak. There is little documentation and almost every function imaginable is in the Object superclass.

Who's your expected audience?

[JavaRob]

Tough one to answer without more info....

Is this an SDK for developers using your own invented language, with compiler etc.?

What other language or environment is it most like? Those are the developers who will feel most comfortable developing with it, so you should model the documentation on standard docs for that language.

General advice -- people learn new things best by doing them. Make sure your docs have a very quick intro to give developers the lay of the land and get them interested, then jump right into getting the full-source, good functionality demos running. The sooner I can create something actually useful to me (probably by modifying your sample app, not coding something from scratch), the sooner I'm hooked.

Then to *keep* me hooked, you'll need a very thorough, easy-to-use reference -- both language elements and error codes/messages. It should have a good index, but also be organized well into good , fairly fine-grained categories (so that I can find what I need when I want to do X even though I don't know the function, etc.).

Qt

[Otter]

TrollTech did a superb job with Qt. Excellent balance of documentation, examples, tutorials and overviews.

Definitions AND examples

[samjam]

You need good examples to SHOW what your definitions mean.

You need good definitions and specifications so developers can extend the given examples to their own situation.

Each new class of capability for a given module will need some examples. Too many trivial examples and not enough meaty examples driver developers mad with rage.

If your SDK has well defined uses, tell a story of a developer writing and refining some code for a given purpose, so the reader can see how and why the more subtle points of the APIs are important.

The PERL 4 Camel book is a good example of this.

Sam

Errors that mean something

[ka9dgx]

If you return an error, make it unique for each actually error source. Resist the temptation to group all the errors together. NEVER us a "general error"... your code knows why it failed, its criminal not to return that information to the calling program.

There's nothing worse that some of the BDE errors from Borland. They're misleading at best, and they lie sometimes.

Remember - The true measure of character is what you do when things go wrong.

--Mike--

Wiki...

[dmayle]

One very bizarre, but incredibly helpful word for you: Wiki

Even if you only do it in restricted form (verified commits on private site) you'll find that the volunteer work of all of your users will give you a much better final product than whatever you release. (Your users can even help out early of you do a release-early release-often model.

You'll get to leverage the power of open-source (the community) because you have a know community already.

On the same topic, something else you might want to provide are skeletons (working stubs that do nothing, but have all of the crap-work already done for starting projects), and a very simple, but fully functional project that takes advantage of the SDK, to show how you expect it to be used.

Re:Slashdot standards?

[smittyoneeach]

You can't write documentation without asserting something about the reader.
Does "no clue" imply that this is the first time they've ever tried coding something?
In this case, you want to write something gentle. The python tutorial is one notable example of what to do there.
However, if you're talking boost, the 100-level stuff isn't going to win applause.
One thing I haven't seen yet in this thread is the task-oriented, or 'cookbook' approach, that serves at least two distinct purposes:

quick-n-dirty steps for the initiated

nice feature overview, to highlight functionality you may not yet be using.
Another thing unmentioned in the thread in indices. For documentation of size, the better the indices, the more useful.

Re:Slashdot standards?

[oojah]

I felt this needed highlighting:

I'm tired of reading documentation that's written like I already understand the system and only makes sense after you know what you're doing. If I already understood the system I wouldn't need docs.

It's an excellent point - don't just document your API, tell us how to use it!

Cheers,

Roger

MSDN

[Anonymous Cowpart]

I must say that MSDN (Microsoft Developer Network) is a very good SDK,
at least when considering the Platform SDK (albeit for a terribly inconsistent API).

Search, Index, and cross-reference are all well-implemented, consistently formatted,
and complete, and updated fairly often. Combined with a choice of format
(HTML help or web browser of choice - even Firebird works well), it is a pleasure to use.