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.
Of course, use WinHelp format.
What is the Slashdot recommended or preferred format for SDK documentation
I didn't realize slashdot was a standards community.
I've read documentation for more things than I care to think of. I've read them in html, pdf, txt, doc, wri, hlp, and plain old fashioned paper.
I could care less what format the documentation is in as long as it's written well. Quit worrying about what format it's in and spend that energy making sure it makes sense and is readable. 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.
Write some documentation that's understandable by someone who has no clue and you'll be set.
For instance
Error: An Error Has Occured
or
Error: Unexpected Error
Thanks for that, really fcuking useful!!!
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.
The single most important part of any SDK is a tutorial that is aimed at absolute novices. You must assume that your users will have had absolutely no prior experience with your SDK, with any similar SDK, or perhaps any programming language. The "Your First Cup of Java" tutorial is a pretty good example of what I mean.
Your tutorial should be simple enough that the most stupid person you can ever imagine using your SDK will find it straightforward. Perhaps test it on a non-technical user like your mother or some kind of office clerk.
You should try to minimise the length of time required to complete the tutorial. Less than an hour is good. The tutorial should let the user understand what your SDK does, how to start using it (including installing it), and what sort of things they can do with it.
SDKs are boring. If you can make the user leave your tutorial with a smile on their face and a good feeling about your SDK, then they will come back for more.
A good tutorial should leave the user feeling confident that they can go out into this new world on their own and survive. This can partially be achieved by concluding with a handful of good links that the user can follow to get more information. For example, give a link to a walkthrough of a simple---but non-trivial---application developed using the SDK. Give a link to the automatically generated API documentation. Give a link to a document that explains the architecture and overall philosophy of the design of the SDK. Give a link to some "do"s and "don't"s. Let the user know where they can turn for help from an actual person.
"The noble art of losing face will one day save the human race"---Hans Blix
If your SDK requires a number of calls to set things up; Document them clearly with a diagram, flowchart, etc.
And the recommended order of setup.
Make sure the developer can differentiate between functions required Before something in initiated, or after.
It can be really difficult to see the developers intent when you have to figure out if you can call a function yet.
Nothing more frustrating than trying to figure out why something doesn't work when the code looks right, and the documentation doesn't say you can't call a function after a certain point (or before another) and you get nothing to indicate there is a problem, except it simply doesn't work.
Example programs are nice, but they only show one way to do something; Often overly simplified. (Example programs are nice to prove a function/process works; if it fails to work I have to assume there is something fundamentally wrong.)
Well, if not me, somebody else experienced documenting SDKs. Technical communication is a specialized skill.
I'm assuming you're not a writer yourself, or don't already have one on staff. You didn't actually say.
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
Few things are more frustrating than to go to the "docs" section of an F/OSS software project and find it's a wiki with lots of "TO DO" headings and no useful information. Here's a tip: if you don't provide any documentation, you won't have any users to volunteer their hard work documenting the code that you know a lot better than they do, since you wrote it.
Now, wiki as a tool to organize and present the docs is another issue entirely. Wiki isn't bad, but simplying plunking down a start page and expecting users to fill in the details is not going to solve the problem of missing docs. You need to populate the wiki with useful information FIRST. And make sure that you offer an off-line version of the docs; some people rip PDF's to their handheld and read them on the bus/train while travelling to and from work.
-paul
Pistol caliber is like religion: everyone has their favourite, and theirs is the only right choice.
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
It's great having tutorials and references and pdfs and stuff, but I love being able to type "man functionname" or "man commandname" find out exactly how something is intended to be used. And the "SEE ALSO" section at the end is pure gold.
There are two kinds of code examples.
1. simple examples that show exactly how to do one thing. keep it minimally sufficient.
2. complete examples that pull it all together.
Many Microsoft SDK sample sets include elaborate supporting infrastructure which means you have to figure the whole thing out in order to understand a single function. DirectX 9 SDK is a prime specimen. It has the type 2 examples, but no type 1 examples. You have to read hundreds of lines of code to learn how to do simple things. The directx 9 samples are an SDK on top of an SDK.
Comer's INternetworking with TCP/IP volume III is another one on a smaller scale. In the parts about setting up simple TCP and UDP sockets, it builds an infrastructure that combines TCP and UDP, rather than just showing the steps for each socket type. Yea, it all looks pretty simple when you have been doing it a while but its hard for a beginner.
I think its in the nature of programmers to fancier than they need to be, because thats the fun part. Sample code is one place you want to avoid that tendency.
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.
I can recommend Doxygen. It allows you to intermingle API documentation and code; you put a specially, but easily formatted comment in front of or behind each thing you want to document (class, method, member, #define, etc.), and then Doxygen extracts the documentation, producing a variety of output formats (HTML, LaTeX, RTF, PDF, and others). A lot like JavaDoc, and a lot like the Qt documentation as well.
For HTML output, I'd recommend using a custom CSS stylesheet rather than the one provided, though. Fortunately, everything is CSS-enabled, so it's easy to change the look 'n feel.
Database engine for analyzed or annotated text
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.
Apart from the things mentioned like documentation, examples, consistency maybe you'd like to build a layered SDK to make easy things easy and complex things possible.
It's of course not very straight forward to get that right but your target audience increases. A tool i used years ago (LabView) did this to excess - not good IMHO, but maybe 2 layers would be good, depending of course on the overall complexity of your SDK.
One great combination is a Wiki, and doxygen for the code docs, class diagrams, etc.
I use docs generated by javadoc often, so I'm pretty happy with the format of the html generated by this program. Anything will do really, as long as it is easy to navigate quickly. However, the thing that is really useful is to be able to know what each method actually does. Describing how to use a method often leaves something missing unless you already have an expectation of how something will work. I find having examples of how some parts work together is a good idea. For a completely fake example, just knowing that connect() and init() are methods in the SDK, it might not be completely obvious that a call to connect() should always be followed by one to init(). I think you get the idea. When I read a doc, I want to know how something should be used, not just what it does.
SIGFAULT
Write some small part of your SDK documentation -- enough to illustrate various aspects of it. Then hire a senior-year university student for a few days to look at it, and explain it back to you. You'll be amazed at all the assumptions you made, that need to be explained.
Bonus points for good samples. Get the college student to write them, and have one of your senior developers review them.
Chip H.
The best documentation I read was from a Borland C++ 3.0 book which included a CODE EXAMPLE with every function.
Better documentation explains why I would want to use the function/method and has common uses of the function/method.
In the library code that I write, I typically write test-first programming, which serves as an API example of how to use the functions.
The best SDK documentation are those written in plain English. Too many geeks developers write their code in latin haiku and expect everyone to be able to understand disconnected thoughts in a lingo that can only be understood if you created it.
Best suggestions:
1. Hire a writer to write documentation.
2. Keep the docs simple and task oriented.
3. Use Framemaker.
4. Only allow the developers a technical review. Never allow them in a final review.
5. Don't try an keep up with the Jones's when writing SDK documentation. Be unique, don't try to clone M$, Cisco, Sun or IBM.
Cheers
moc.oohay.cnihtt (-\-)
one thing i have not seen mentioned here (ok, maybe i overlooked it ;) is the importance of not terrifying users with thousands of settings; if there are possible default settings that make real sense set them up in the api if it is unlikely that users want to change these. at least i do prefer it that way; and alternative extended functions (for example) are much better.
Good documentation serves multiple different purposes. It should introduce new users to the tools, and assist them in answering the question, "is this the right tool for my needs?". It should help the user to understand how the tools work. It should give practical examples of how to perform various tasks. It should serve as a definitive function reference for skilled users. And it should be easy to search.
....), where fs is a valid format string, cs is a valid command string, ..." Accurate, but not worth the space it took up.
The first, introduction, requires a good table of contents, and some good overview and structural documentation. This cannot be automatically generated, and should not usually be written by the developers. The skills involved in good technical writing and good coding don't usually overlap that well.
The second, understanding, is an extension of the first. It should blend practical, real-world-type examples with subject-by-subject introduction and overview. The purpose here is not to teach "how to do [blank]" so much as to explain enough of how [blank] is done to allow readers to start putting the pieces together for themselves. Some tasks require contra-intuitive setup and tear-down, or an understanding of how the setup and tear-down tasks are intended to function.
The third, practical examples, can be partly automated. Two warnings:
1: Real code isn't necessarily the best example. Often, real, production code has dependencies or compromises that makes for over-complicated examples. Have a non-techie read it for sense.
2: Keep examples small but complete, and include the values of parameters where possible. I recently saw a fully accurate example for a vendor's API that was absolutely useless. Four of five function parameters were either custom format strings of bar-delimited command sequences, and nowhere were there examples of format strings or valid commands. The example was something like: "ExecPFECommand(fs, cs,
Fourth, a definitive reference, should be automated as much as possible. Keep in mind that real-life function names and parameter names can be cryptic. If they are, fix them up or alias the formal parameter names in the documentation to something meaningful. It's got to be correct; that's why so many people want to automate this kind of documentation. Beware of things that can trip up automated documentation generators. Sometimes developers add extra parameters to functions, for "the next version". Document that they are unused. If they must be NULL, then document that as well. Sometimes features are removed in non-obvious ways. Consider an API with an object that implements a printf() style formatted output function. Suppose a developer originally intended to support all the printf format-codes, but later they reduced this to a subset. Remove the references to format codes/options that the API no longer respects.
Fifth, search ability, is critical. This involves more than just having a decent search engine; you also need a human being to identify keywords and tag pages in the documentation to build high-quality indexes.
A few additional points:
Keep terminology consistent and avoid generic terms with existing meanings. Example: same vendor as above, used the terms Object and Entity in non-standard ways in a system using both objects and a relational database. Better to either qualify the term (PFEObject and PFEEntity, for instance), or come up with something else.
Watch out for cruft in function, variable, object and structure names. If you're lucky, it would be no worse than the Afx-prefixes all through Microsoft's MFC libraries. If you're not, you end up adding more people to phone support to explain defects in the documentation.
Plan for obsolescence. If various interfaces aren't really generic, don't pretend they are. You didn't mention languages, so I can't be specific. C++ for instance would let you use namespaces for multiple versions. But you might want to encode the application version in the names. But you might want to encode the application version in the function and type names. It's ugly, but it does work. And most people here would rather have "ugly but works" over "attractive, but breaks often".