HOWTO Document and Write an SDK? 78
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?"
Think about it (Score:4, Insightful)
Re:Think about it (Score:2, Insightful)
And don't just think -- use the thing for real-life work yourselves. I cannot see how one can come up with a good interface without that feedback.
What helps me (Score:5, Interesting)
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.
Re:What helps me (Score:2, Insightful)
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
Re:What helps me (Score:3, Informative)
Sun's guide to writing JavaDoc [sun.com] has lots of good ideas
Re:What helps me (Score:1)
I readlly liked the way the graphics chapter was set up too, each function started with a base graphic and showed what would happen if this function, with arguments, was applied to the graphic in question.
Sadly I don't
Re:What helps me (Score:2, Informative)
The problem with including tutorial or extensive sample material in API documentation is it's too disparate, and not useful when dealing with more compl
Re:What helps me (Score:1)
Re:What helps me (Score:3, Informative)
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
Re:What helps me (Score:2)
While not a SDK, take a look at the book On To C [aw-bc.com]. This is the best programming book I've ever read. It is example heavy and assumes the reader already is familiar with programming. For example, it doesn't attempt to explain what a variable is or why you'd want to declare one, just how to do so
Re:What helps me (Score:1)
Uhh, this may be true for some parts, but lots of the documentation is crap. Look for example at javax.swing.text.rtf.RTFEditorKit: "We didn't wrote this but hope to improve it later" or even better javax.swing.JViewport: "Hey we have a cool and fast implementation but won't tell you what a JViewport is". The API docs are full of this, a
Re:What helps me (Score:1)
Re:What helps me (Score:1)
Re:What helps me (Score:2)
I don't know what version of the javadocs you are looking at, but in my version the first sentence of the class description tells you what a JViewport is.
Documentation formats (Score:3, Interesting)
Re:Documentation formats (Score:1)
Html is nice, hyperlinked pdf is better. You can browse it on your computer and can also make printouts, which is nearly impossible with html documentation.
Re:Documentation formats (Score:1, Interesting)
I use Linux at work, and Adobe's version of Acrobat reader for Linux is several years out of date. It very frequently crashes X altogether.
An open standard, like HTML (with intelligent CSS which will allow you to print well), is far better, and there is no reason that a halfway decent CSS guy can't make HTML look very good for printing too, and if that HTML was generated from XML, then it
Re:Documentation formats (Score:1)
I use Linux at work, and Adobe's version of Acrobat reader for Linux is several years out of date. It very frequently crashes X altogether.
The latest linux version of the reader (5.0) is not the most recent, but it is not years out of date. And you are not bound to adobe's version. You counld also use one of the many alternatives.
An open standard, like HTML (with intelligent CSS which wi
Who's your expected audience? (Score:5, Insightful)
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.).
Re:Who's your expected audience? (Score:2)
Mod parent up. Whatever it is, it should pass The 15 Minute Test [pastiche.org]. Some developers may look at it in their spare time and there aren't a lot with enough patience to sift an hour through documentation before starting.
Qt (Score:4, Informative)
Re:Qt (Score:1)
Of course, the documentation is matched with an equally good design and API. The same level of documentation wouldn't have nearly the effect if it were matched with Motif, for example.
Definitions AND examples (Score:5, Interesting)
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
Errors that mean something (Score:5, Insightful)
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--
Re:Errors that mean something (Score:3, Funny)
BDE errors are terrible to say the least. Here is my favorite: $2E3B : Query makes no sense.
Write 1 (Score:3, Insightful)
Wiki... (Score:5, Insightful)
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.
Wiki is not a substitute for proper docs! (Score:2)
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
Re:Wiki is not a substitute for proper docs! (Score:2)
Re:Wiki is not a substitute for proper docs! (Score:1)
WinHelp (Score:1, Troll)
Slashdot standards? (Score:2)
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
Re:Slashdot standards? (Score:4, Insightful)
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 [python.org] is one notable example of what to do there.
However, if you're talking boost [boost.org], 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.
Re:Slashdot standards? (Score:4, Informative)
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,
RogerRe:Slashdot standards? (Score:2)
An SDK is not something used by the average person. You've got to already know at least some things before jumping into one. The SDK documentation should not worry about teaching people what an SDK is, but let people know how to use it. Explain what the different pieces are for and what they do. Give at least one example of exactly how to use it. Give a link or something to point people who need more info to another resource like forums or a mailing list
MSDN (Score:4, Insightful)
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.
Re:MSDN (Score:2)
At a minimum, recognize that the tutorial, the manual, and the reference guide are three seperate pieces of documentation. If you try to combine them all into one big document, I will hate you.
Re:MSDN (Score:2)
Re:MSDN (Score:1)
Re:MSDN (Score:2)
What are the list of supported flags, and what does each do? Here's the quoted text on that page:
Re:MSDN (Score:2, Informative)
What other flags have you seen used?
Re:MSDN (Score:1)
Re:MSDN (Score:2)
1. If you have no idea where something would be located in the library, you may be in for a long, long search. More than once I've searched for things and to me they weren't in very intuitive locations. That's an MSDN issue though, not necessarily indicative of SDKs in general.
2. SDKs for MS at times will give awful examples. As
Cross-language conversions (Score:2, Insightful)
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
A Tutorial for Absolute Novices (Score:2)
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" [sun.com] 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
Required Logic should be outlined (Score:2)
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 y
You could... (Score:2)
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.
Documentation (Score:3, Insightful)
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...
Good analogies and metaphors (Score:2, Informative)
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 j
My perfect SDK (Score:3, Insightful)
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.
MySQL, and *use it* before publishing! (Score:3, Informative)
I have often looked to MySQL's html documentation [mysql.com] 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 [archive.org] 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 [faqs.org].
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
man pages (Score:1)
two kinds of code examples (Score:2)
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 di
Provide a test harness (Score:2, Insightful)
DoxyGen (Score:1)
I can recommend Doxygen [doxygen.org]. 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.
Discussion summary: 10 tips (Score:1, Informative)
Use patterns! (Score:3, Insightful)
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.
method use (Score:2)
Get an outside opinion (Score:2)
Bonus points for good samples. Get the college student to write them, and have one of your senior developers review them.
Chip H.
Examples and explain common uses of the API call (Score:1)
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.
Some guidelines (Score:1)
The first, introduction, requires a good table of contents, and some good overview and structural docu