Suggestion for API (nextgen)

[Glen Lipka]

I know you guys are working on a new API page.  I had mentioned a suggestion to Joern.  He suggested to post it here.

The suggestion is to have a "samples" link on every single API call.  This would link to a page with a list of stand-alone samples of that call.  Many API calls would need just one single example, but some would need more to exercise the different options.  I think it's important to be able to see the API in action to really get it.  If the samples are on a Wiki, then the community could add to them and contribute.

I think it's also important to separate the samples to individual single use case.  So many pages have 30 samples on one page and its impossible to cut/paste the one specific one you want.

This also applies to selectors.  I see E ~ F, but without an example, I just don't get it.  Knowing how advanced selectors work make using jQuery so much more powerful.

Anyway, I hope this is useful for you.

Glen

[Andrey Fedorov]

I agree whole-heartedly, that the examples are one of the most important parts of an API's documentation. Examples are what will give people ideas as to what you can do with the library, and will unavoidably be copy-pasted into projects all the time. Having good examples means the library will be used more as well as more correctly.

Josh Bloch gave an extensive Google Talk about this: How To Design A Good API and Why it Matters

Cheers,
Andrey

[Glen Lipka]

The kind of "sample" I am talking about it like this:
http://www.commadot.com/jquery/selectors/api.htm
(Although it's a little ugly)

This could potentially be extended to work sort of like this page:
http://www.w3schools.com/js/tryit.asp?filename=tryjs_text

But the point is making easy to cut/paste.
My example lacks the ability to navigate to other API calls.  I can add that.  The template needs work, but this is just a proof of concept..

Glen