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

Qt

[Otter]

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

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

Re:What helps me

[Software]

JavaDoc is nice, but Sun discourages the use of sample code in JavaDoc. For this reason, I find JavaDoc less useful than Microsoft's MSDN documentation or the documentation typical of a Perl module. JavaDoc is good when you can't remember some detail about the object or method you're using, but it's not good when you're just starting out. Sun would say, "That's what a tutorial is for! JavaDoc is an API reference, not a tutorial.", but why not have both?

Sun's guide to writing JavaDoc has lots of good ideas, regardless. As does Sun's guide to API specs.

Re:What helps me

[pavon]

There are two things needed to learn a new system quickly - a good reference giving the details of every function in the SDK, and documents giving the big picture. The former is pretty easy to understand how to do well and there are good tools like javadoc or Doxygen that help with this task.

The latter is the one that is lacking most often. You can see very quickly whether a geek or technical writer was in charge of the documentation. If it was a geek this document is non-existent, and at best you have few code examples to help you get the big picture.

If it was done by technical writers it is extremely verbose, baby-stepping you through everything. This is something that mangers have a hard time understanding - if documentation is so overwhelming that it is faster and easer to learn by jumping into the code, then you are not much better off than when you had no documentation at all.

My suggestion would be to write a document that you would like to read. Give a quick overview of the organization / concepts of your libraries, and then quick code examples demonstrating how they fit together. If there is something that seems to verbose, or explains things that every computer programmer should know, either take it out or maintain two documents - the "expert" overview and the tutorial.

If there are any common pitfalls/misconceptions with your SDK (and you can't change the SDK to improve the situation) make sure they are in there. It is sometimes hard to write this yourself as you are already familiar with the SDK, and so you may not think to put down some things. For this reason, you should get help from people who are programmers but are not familiar with the SDK yet and/or are in the process of learning it. If there are any common questions, that means the documentation is lacking in that area. And of course this does not supersede the need for more in-depth (and well commented) code examples.

Good analogies and metaphors

[slimemold]

Any time you are trying to explain something, you have to bridge the gap between what they already know and understand, and what they need to know and understand.

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.

MySQL, and *use it* before publishing!

[TTK Ciar]

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

Re:MSDN

[The Bungi]

I've been writing Win32 code for 10 years and I've never seen "other flags" used there. And STACK_SIZE_PARAM_IS_A_RESERVATION is rarely used because it's safer to just set the stack reserve in the app's image header, though that is supported under WinXP/2003. You usually use CREATE_SUSPENDED, and even that is rare.

What other flags have you seen used?

Re:What helps me

[ievans]

They usually do provide both. I work on the J2EE Tutorial, which documents the APIs included in the J2EE platform. There's also the Java Tutorial, which documents the standard JDK/JRE platform APIs. For other APIs, check the BluePrints or other tutorials & code camps. Not to mention the case studies and the code samples bundled with other distributions.

The problem with including tutorial or extensive sample material in API documentation is it's too disparate, and not useful when dealing with more complex applications that use a number of APIs. If you're writing a servlet that uses JDBC to pull data from a database, where does the sample code go?

-ian

Discussion summary: 10 tips

[Anonymous Coward]

1. Be careful about how you name things. If you are writing .NET code, there are established guidelines. If not, you can use a general guide to naming things or, chances are your platform documentation has its own guidelines already. Don't waste your time trying to invent new ones, you'll simply confuse your users.
2. Provide lots of examples.
3. Use your own SDK! The best way to do so is to write unit tests. You can then most likely use a lot of that source code directly in examples, thus ensuring your examples always work. (minus the asserts and 'failure tests', unless you want to prove a point, etc.)
4. If u kant rite professional english and complete sentences, hire someone who can.
5. If possible, segment the reference for different classes of users: beginners who have never used your API and experienced users who are trying to squeeze it for what it is worth.
6. Use appropriate tools (NDoc, Doxygen, RoboHelp, etc.), especially if you can create several output flavours (PDF, CHM, HTML, etc.) from a single input. Bonus points if it's part of the source code itself (i.e. as special comments) as there is less chance of a synchronization error.
7. Hyperlink as much as possible. This will make easier for the user to discover features.
8. Make it easy for your users to report documentation bugs. A Send feedback on this topic link at the bottom of each topic (like a lot of MSDN) is a great way to make sure documentation errors don't stay hidden too long, because incorrect documentation is worse than no documentation at all!
9. Beware of pointless documentation such as: "The 'EnableJrtOutput' property allows you to enable the output of JRT." Explain what JRT is and why people would care to turn it on or off.
10. Your documentation is as important as your code. It should thus be QA'ed (reviewed) as intently as the rest of your product. Don't put off documentation to the last minute.