What Features Do You Look For in a SDK?

MadCow42 queries: "I'm in the process of putting together a 'Developer's Kit' for 3rd-party developers to use while writing front-end applications that hook into our software (our software runs a digital printing system). I've included a complete XML command language specification for our system, sample XML input and output, and simulation software they can use during development. What else would a developer want? From your experience, what makes a truly 'great' development support package? What can I do to make developer's lives easier?"

What oughta be there

[haplo21112]

Practical Code examples lots of 'em. Show a useful example of how to use every single function, and everyone of its options.

Re:What oughta be there

[Anonymous Coward]

Yup.
Source code, source code, source code and a simple, effective way of looking up functions & methods.

Re:What oughta be there

[MrBlack]

Couldn't agree more. Examples of varied lengths are good. I find it frustrating when SDK demos try to make the product/API look good by glossing over the things that are more difficult to do using a give product/API *cough* Microsoft *cough*. I'd like to know about any gotchas and sharp edges up front. To echo what others have said good docs + good demos = good sdk.

Not sure if this is applicable....

[heliocentric]

But I took a java class recently and we had access to the JavaTM 2 Platform, Standard Edition, v 1.3 API Specification and the listings of the fuctions was great, however lacking a search made for harder answers to "hmm where is the random number generation functions." If your stuff resembles this documentation about your functions, please add a search.

Documentation

[wrinkledshirt]

Get somebody who knows how to copyedit and knows a thing or two about programming, and pump out as much stuff as possible. Locate it centrally on a website somewhere so that anybody can access it immediately. Accept feedback for corrections, suggestions and examples.

Take a look at PHP's website [php.net] (currently they have a sympathy message on their homepage, you can progress from there). It's support section is great, and many people can help themselves through it.

Re:Documentation

[mini me]

You've got that right about PHP. Their language reference section of the site is superb. It makes it quite easy to program in PHP when you have the whole API with in-depth information at your finger tips. They also allow user comments about each function which can even more deeply explain what the function does, or how it can be extended.

I would definitly recommend you look at that for some ideas. But definitely, like others have already mentioned, include lots of example code, that's the best way to see how something works.

Some simple suggestions

[Ridge2001]

First things first: the user should be able to install the SDK easily. If the SDK is just a single self-contained directory, it is okay to simply provide everything in a single .tar.gz or .zip file. Please MAKE SURE TARBALLS UNPACK INTO A SINGLE NEW DIRECTORY. [linuxdoc.org] If the installation is more complicated (the SDK uses the Windows registry, or needs to be installed as root under Unix) you'd better provide an .rpm, a windows installer file or the like. Make sure you can uninstall and reinstall the SDK cleanly as well.

In the top-level directory of the SDK, there should be a simple text file named README or README.txt. If it isn't there the user has to go hunting around in a bunch of incomprehensible directories searching for documentation and gets annoyed. This README file should point to the location of the main documentation.

The main documentation should consist of, at minimum, a tutorial and a reference. One of the first things that should show up in the tutorial is a description of the directory hierarchy of the SDK (this could be in the README instead). It seems many SDK creators are so familiar with the structure of their own SDK that they forget to tell their users about it, leaving them to wander about in a sea of incomprehensibly named files and directories. You should describe the purpose of each directory (and possibly even the files inside). If you're developing for Unix or Java, it helps to use a conventional naming scheme for your directories -- bin/, lib/, src/, and so on. (For Windows or Macintosh you might want to use longer, descriptive names if you fear your users will be unfamiliar with terse Unix-style names.)

Some SDK writers just toss a bunch of code examples in a directory somewhere, with no explanation of the who, what, when, where, why and how of using them. (Sometimes they don't even have comments.) The tutorial should have a prose description of the code examples. You want to aim for a literate programming [dmoz.org] style. Make sure the tutorial is clear to newbies. Have someone read it over before you release it. I don't mean having one of your fellow SDK developers read it for typos (although you can do that as well); have someone unfamiliar with the product read it and make sure it is understandable.

The reference documentation should have complete, detailed explanations of every class/function call/XML element/whatever. If possible, use a standard format appropriate for your platform (e.g., man pages, Javadoc). In all cases you should try to use a format which is as non-proprietary as possible (e.g., HTML is good, PDF is okay, MS Word is pretty dubious).

Other documents may not be mandatory but can be nice to have: a FAQ, a rigorous specification, a style guide, a tool guide.

The user should not have to modify files in the SDK directory itself. I always like to keep a software package as pristine as possible, so I don't have to keep wondering whether I screwed up some configuration file or not. If you must have files modified in the SDK directory structure, keep it confined to as small a location as possible (a single configuration file, or at least a single conf/ or etc/ directory). Make sure it is easy for the user to compile/execute their own files/programs outside of the SDK directory.

If you plan on making releases (especially beta releases) often, it is nice if users can have multiple versions of the SDK installed at the same time. Also, try not to completely reorganize the SDK with every new release. Pick an organization and stick to it.

Make it a community

[mnordstr]

I don't know if this really is appropriate for an SDK, but several of the online documentations for programs (ie. PHP Manual [php.net]) have user provided comments which I think are usually the best part of the doc. They contain what users don't find in the normal documentation, and automatically completes your doc.