Slashdot Mirror
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?"
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.
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.).
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--
Maybe I misunderstood, and you're writing SDKs for two seperate things, but I highly recommend against writing two seperate SDKs for the same system. It more than doubles the effort. If you need to give your corporate users more power, offer extensions to the original SDK, so that the two are the same except for one extra bit. That way, corporate folks can use the other stuff, and the other folks know precisely what they're missing.
Not just code examples but both non trivial examples and trivial examples. A reference application allows the developer to see how the design fits together (and can be used to test the viability of the design), while trivial examples allow copy and paste programming which on some projects is deadline dictated.
Sun's documentation is very well done. What is more is most of the various add ons are well documented, Javadoc really works well.
Also it helps a lot to have a nice quick start. Really look at what a lot of embeded systems companies have done lately, there is a serious push to do everything possible to just let the develepor to get on with life. Mostly it is just detailed documentation, just add water examples, and lots of communication (i.e. if you are having trouble with something you will end up speaking to the engineer who did that section.).
I'd do something interesting, but my server can't handle a slashdotting.
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.
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.
Get thee glass eyes, and, like a scurvy politician, seem to see things thou dost not.--King Lear
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.
You haven't said which programming language the SDK is in, but one thing that makes a bad SDK is one that's a literal translation from an API in a different language.
Case in point:
A Java API for a commercial product is based on the earlier C API. All the magic handles are properly translated to objects, but sometimes the internals stick out. It has a method you can (or, as it turns out: must) call to set the character encoding the library uses to communicate with the server. This makes sense for C, which needs to be told, but if all of your Java API uses Strings, a method like this is nothing more than a please don't suck method you have to call, or things fail.
Make documentation in such a way that programmers which have already your API's before (or similar ones) don't have to read the whole manpage/docpage for a given function in order to know some detail.
This might involve some redundancy, but I prefer it that way. For example, the good linux manpages are usually separated by sections (description, return values, etc). If I'm already familiar with, say, the recv call, I don't want to read through the whole manpage in order to know what the function returns when the remote host has shutdown the connection. I simply go to the "return values" section and everything is possibly repeated there.
And the most important - don't let your documentation rot as the API is updated...
The AACS key is NOT 0xF606EEFD628B1CA427BEA93A9CA9773F
The perfect SDK, to me, has a "two faced" nature. The first face is a dumbed-down thing that makes it easy to get started, or to use some shallow function of the SDK as part of a project that's mostly focused on something else.
... it should come with an example, or set of examples, that compile right out of the ... the interfaces should use base types as much as possible (strings, arrays of bytes, ... the user shouldn't have to install many dependencies for aspects of the SDK he isn't going
1. It should be easy to do an obvious thing with the SDK, without reading the whole manual.
box and are maximally simple.
filenames) to make them easier to invoke, even if this is not general enough for
all purposes.
to use.
The second face exposes you to all the details, and the maximal generality. Here, reader and writer objects (or whatever is appropriate for your language) take the place of files and byte arrays, unicode support is standard, etc. Generally the first part is just stubs around this.
In my opinion, there's no reason to provide middle ground, and it tends to clutter the interface.
IMO, the SDL is a good example of a well-designed SDK.
Provide a test harness (with source) that executes the api. Provide a debug stubbed version of the api that returns hints as to why the parameters failed. Be very clear on calling conventions. Who should allocate and free the memory. Be very careful when you pass out handles to records what they are for.
Assuming that by SDK you really mean "some sort of framework", you should read the Documenting Frameworks Using Patterns paper.
The approach they describe works quite well, and is easy to do incrementally, and easy to use for developers. Of course, you still want reference documentation for individual modules/methods/functions, but that's not going to be much use by itself.
Pretend that something especially witty is here. Thanks.