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.
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.
There is nothing wrong with being gay. It's getting caught where the trouble lies.
You need to use a documentation framework to automate the process, unless your SDK only has one or two functions. I like Doxygen a lot, it's pretty easy to use and works with lots of languages. JavaDoc or PerlDoc, etc are good for specific languages. Html is a fine file format for the final output.
-73, de n1ywb
www.n1ywb.com
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.).
TrollTech did a superb job with Qt. Excellent balance of documentation, examples, tutorials and overviews.
What I'm listening to now on Pandora...
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
blog.sam.liddicott.com
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.
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 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,
RogerDo you have any better hostages?
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
When a programmer first learns about data structures, s/he might learn about "trees". Imagine explaining a tree without the implicit metaphor of roots, branches, and leaves. Sure, you could do it, but not without a lot of pain. Maybe it would be a "pointer-based hierarchical polyfurcating network of arbitrary data nodes".
But it goes beyond just explaining the concept. If your analogy is any good, many items are, at a basic level, self-documenting. A debugger or profiler, for instance, uses the analogy of a VCR. You already know what the play, pause, and stop buttons are likely to do. You might consult the docs to see what exactly the difference is between pause and stop, but whatever it is it won't be a big surprise.
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.
I have often looked to MySQL's html documentation as a shining example of what documentation should be like. It has a pretty good API, too. I usually haven't the time to do a really knock-up job of my own documentation, but I do try to look at MySQL's for my general approach, including the format (html). Here's an example of some of my documentation. I borrowed some pointers from the standard UNIX man page format, too, because it's been in use for a long time and developed into something reasonably complete and useful.
Another good example (imo) is the RFC which defines the NNTP protocol, rfc-977.
Know your audience -- the HOWTO I wrote was primarily for nonprogrammers with rudimentary knowledge of UNIX command line use (waybackup's primary expected users), but also for programmers who might be trying to debug or extend my code.
The most important thing with a SDK or any other tool, in my opinion, is use it a lot before publishing it, or even considering its development complete. Don't just come up with artificial examples, but actually use it internally to solve real-world problems. Your developers will unavoidingly find really annoying little problems in need of fixing, and come up with time-saving functions (perhaps just wrappers around already-existing API functions) which might need to be added to the SDK. Perhaps there's a function which seemed reasonable at the time, but in actual practice leads to runaway memory consumption. Maybe there are several functions which often get used together, but require the programmer to keep track of parameters which could get hidden internally instead. A nice long beta test, with the expectation of many programmer hours spent in reaction to user-reported errors/suggestions, is also often a good thing.
In fact, as a programmer I usually tailor my development effort towards getting something minimally useful first, and then actually use it, and let my use define further development. Features that sound good "on paper" are often a waste of time to develop because they don't actually get used. Also, thinking real hard at code does not necessarily make it better than code which has been shaped by real-world usage.
Anyway, I'll shut up now. Good luck with your SDK!
-- TTK
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.