Friday, March 16th, 2007

Docs for Dojo, Prototype, Others?

In my recent post on current concerns with Ajax, there was a comment about lack of documentation for Dojo and Prototype. In the comments (of the Ajaxian post and my blog post), project members asked what would you like to see wrt documentation?

Here’s my wishlist for Ajax framework docs, in particular Dojo and Prototype:

  • Project/documentation portal A single page linking to all relevant documentation, with simple categories.
  • Task-based. Documentation based on typical tasks users (developers) need to perform, not just a walkthrough of the API. The Yahoo! UI docs is a good example of this. Dojo has a few tutorial-style articles that approach what I’m talking about, but not enough components are covered.
  • API reference Less important to me, but in an ideal world, there would be accessible documentation on every class/function.
  • User-commentable PHP leads the way here, with the official API docs allowing user comments at the bottom (example). No-one can anticipate all the issues that will arise, so why not open up docs to the developer community? Allowing user comments is also an easy way to help keep the docs up to date (if something of a compromise.) It could also be done as a wiki, if the wiki is managed well. (The Rails wiki is a good example of a well-maintained wiki that receives frequent contributions from people in the know.)
  • Up to date This one is more difficult for open-source projects, so realistically it has to be considered a nice-to-have at best.
  • SEO’d So I can google for a component name and easily find the official docs for it.

I believe we have some good examples of docs in the Yahoo! UI library, Scriptaculous (which includes Prototype sort of), and Mochikit, and probably many others too. Prototype also has the benefit of being included in many Rails books. Dojo is an excellent library, and would probably be used a lot more if some work was done on the documentation side.

What’s on your Ajax doc wishlist?

Posted by Michael Mahemoff at 8:11 am
21 Comments

++---
2.8 rating from 47 votes

21 Comments »

Comments feed TrackBack URI

This guy is clueless. Prototype has great documention and an awesome mailing setup to answer most everything. If he wants examples he can go to http://www.prototypedoc.com/ , http://www.prototypejs.org/api , http://tinyurl.com/rncu3

Comment by annoyed — March 16, 2007

@annoyed – I actually thought Michael’s suggestions were quite good, and based on my review of the Prototype documentation (@prototypejs.org/api), he is spot on with his suggestions (although I personally wouldn’t find the SEO’d one that useful, I could acknowledge its usefulness for newbies searching for an answer to the “what does this function do?” question).

Comment by Peter Mularien — March 16, 2007

On second glance you are right. I would like commentable api documentation like php. I over overreacted. 8)

Comment by annoyed — March 16, 2007

Michael: your link to the previous post is horribly broken (unless you want us to try to log into someone’s WP instance).

Comment by Tom Trenka — March 16, 2007

I actually think the Prototype documentation as it currently stands should be aplauded. It was put together by the community and is much much better than what was there before (nothing).
As far as I know the prototype dev team are happy to accept any extra documentation from the community to help expand and perfect the documentation.
Making it commentable only adds to confusion and inacuracies as I rarely see tow developers agree on the same way of doing anything without a debate first.
If you want to comment on the docs mail the team, if you want to offer a suggested improvement to the code, mail the team. If you want to debate the way things should be, start a blog, mail the team and see if they’ll link you.

Comment by Shaun — March 16, 2007

“Dojo is an excellent library, and would probably be used a lot more if some work was done on the documentation side.”

I would wager that this is completely understated. Working with Dojo is completely frustrating at points because of this lack of docs, and even outdated and incorrect docs. I’m curious how many people continue to work with Dojo after checking it out because of this.

Comment by Sam Hill — March 16, 2007

I personally think making it commentable is a great idea. I’ve found numerous solutions for PHP using the comments.

Comment by Thomas Messier — March 16, 2007

@Shaun
Comment able documentation does often give examples with multiple ways… however. This can be useful two, it opens people’s eyes to more than one method. Since, as you say, developers cant agree on one way… isn’t it best to show all the ways people can contribute and they can be discussed.
I find this feature in the PHP documentation hugely useful. Quite often I don’t quite manage to understand the function/object until i see an example that somebody has posted.

@__POST__

I think this post brings up some important issues that should be resolved. However, the documentation for some things like prototype is not THAT bad. We can deal with it for the moment… I feel there are bigger issues that are mostly highlighted in ‘current concerns with Ajax’ article mentioned in the post.

Comment by Dougal Matthews — March 16, 2007

jQuery has a lot of thought/effort put into its documentation. If fact, many of the contributors to the project went there in the first place because they were put off by what was, at the time, not much documentation for Prototype.

Comment by Brian Miller — March 16, 2007

I second Brian M’s comments – we’ve just moved over to use JQuery as our base framework precisely due to its great documentation & examples, which more or less answers the original poster’s compaints over the other far more bloated JS frameworks

Comment by Simon Jenkins — March 16, 2007

I’ll just chime in here to say that Mootools has full documentation and a tutorial wiki (that I authored). It goes a long way towards making the framework accessible.

Comment by Aaron Newton — March 16, 2007

User-commentable docs is perhaps one of those things that needs to be experienced to fully see the benefits. I didn’t give it too much thought until I started playing with PHP, and once I did, the benefits were obvious and I find it’s actually one of the best aspects of PHP development. Any ambiguous or feature is usually explained in a post or an entire thread of discussion (conceptually speaking as the comments don’t actually support threading.)

Incidentally, there was also the Javalobby project to essentially wikify the official Java documentation, which Sun blocked. That would also have been pretty useful.

Comment by Michael Mahemoff — March 16, 2007

Shaun, I applaud the current docs of prototype and dojo too. There’s been a lot of effort on both of them, but there’s still room for improvement, which is probably why people associated with those projects asked for specifics.

Comment by Michael Mahemoff — March 16, 2007

I believe Prototype’s documentation, is on par with jQuery, mooTools and anything else. It has got full api documentation with example usage, and as others have mentioned, lots of sites with working examples/extensions. Though I do like a lot of the suggestions Michael put forth I do have a couple of issues. First, I don’t understand why jQuery and others were not listed as not meeting the mark. What Michael is asking of “documentation” is well beyond the normal realm. Second, (comment related) I don’t know how the ‘bloat’ work got started but it’s far from the truth. Just because you don’t use a method doesn’t mean it is not useful. Third, (comment related) the fact that Prototype/Dojo devs want specifics isn’t a sign of lacking documentation, it’s a sign of a core dev group that is eager to please and work with the dev community.

All in all I think all the current frameworks could be enriched from these suggestions.

Comment by jdalton — March 16, 2007

@JDalton

Thanks for your comments. I only listed libraries I have used personally. Nothing should be assumed about the absence of any other libraries. JQuery, MooTools and many other libraries presumably meet the mark too.

Agree, what I’m asking for is beyond normal for open-source projects … it’s a wishlist and when it comes to the realm of open-source documentation, I have plenty of wishes!

“the fact that Prototype/Dojo devs want specifics isn’t a sign of lacking documentation, it’s a sign of a core dev group that is eager to please and work with the dev community.” True. That’s how I interpreted their requests as well – both teams have done a tremendous job working closely with the community, so it’s natural to assume that’s why they were asking for specifics.

Comment by Michael Mahemoff — March 16, 2007

We were holding back on announcing this, but…at Dojo, we’ve been working pretty hard on getting a full-fledged Drupal-based web site up, and it should be live next week sometime (if not well-designed; it’s a labor of love and a work in progress). We are doing this in response to many things, not in the least to address a lot of the wish list you have up here (as well as others). We’re looking to get all of our materials under a single website (as opposed to being distributed between dojotoolkit.org, Jot, Nabble, and a few other places); we’re creating a set of forums which will eventually replace the mailing lists, and we’re doing as much as possible to make the experience of using Dojo a much more pleasurable experience. That includes breaking up Dojo into three more managable projects, the core of which will be very stable–and a “DojoX” project where a lot of the cooler, more unstable code will live (such as the new Dojo Offline and the Dojo Charting engine). We’re also working on a web-based build tool, to make creating a single JS file from a profile a much easier (and less dependant) experience. Keep your eye on dojotoolkit.org.

Comment by Tom Trenka — March 16, 2007

I think, you miss one point: we need access to outdated documentation. Especially in high-traffic and real business websites you cannot change the files of a framework with each and every release. So I use moo.fx in a six or eight months-old version. Today I will not find any documentation at all. And unfortunately there is no documentation as a pdf or chm that you can preserve.
Thereofor the slow development process of prototype is better for the bigger apps and jquery is better to be implemented in my blog or an experimental site.

Comment by Jens Grochtdreis — March 16, 2007

Michael, let me address these one by one:

* Project/documentation portal: Do you mean having a list of links to every single page in the documentation? A docs sitemap of sorts? This is a possibility for the future. In the meantime, some of our users have generously contributed compilations of the API docs in PDF and CHM (http://prototypejs.org/api/).
* Task-based documentation: like Dojo, we can improve in this area. But we do have a handful of tutorial-style articles at http://prototypejs.org/learn. I’d love to expand this to link to some of the best third-party tutorials out there. And at some point Justin Palmer will likely post on the official site updated versions of the tutorials he’s written on Encytemedia.
* API reference: Covered.
* Up-to-date: This has been a point of emphasis for us. We didn’t release 1.5.1_rc1 until all the new stuff was properly documented. Plus all the new stuff is clearly marked as such so people know it can’t be used in 1.5.0.
* User-commentable: This is something we wanted from the start, but ended up postponing to a later date because of technical and time constraints. In the meantime, we invite discussion about the docs on the prototype-core mailing list (http://groups.google.com/group/prototype-core). If you have something to add to (or correct on) a specific doc page, post a message there and someone on the core team will take care of it.
* SEO’d: All our API pages include the method name in the title of the page. Google searches shouldn’t be a problem.

Thanks for this feedback. Most of the criticism Prototype receives doesn’t come in the form of actionable items.

Comment by Andrew Dupont — March 16, 2007

相比来说prototype的文档还是太少了。
Yahoo UI Library和jQuery的文档比较齐全,学习起来方便些。
没有用过dojo。

Comment by CSSer — March 16, 2007

Andrew,

* Most importantly, just a single page listing the root of all external documentation would be great. The closest I can see is http://www.prototypejs.org/learn, but (a) it’s really only a link to some general Ajax stuff, the blog, and the API. No tutorial links or links to prominent external pages. (b) I think it would be nice if it would be a bit more structured, e.g. Not trying to set up a competition, but I think the Yahoo! UI page pulls off what I mean by a doc portal http://developer.yahoo.com/yui/. It shows you can have a lot of links on a page without it being cluttered.
* API docs are good
* I agree on linking to third-party tutorials from a portal like /learn, since there are quite a few useful ones for Prototype.
* Respect for taking that attitude to keeping docs up-to-date
* User-commentable probably takes some work and needs registration or captcha, and is sadly rather rare for most frameworks and languages. I hope it happens at some stage though.
* SEO. Yep, (though I’d like to see you at #1 for “prototype dollar” ;).

Comment by Michael Mahemoff — March 17, 2007

Free Dojo eBook:

http://www.heronote.com/files/Dojo.htm

Free Prototype eBook:

http://www.heronote.com/files/Prototype.htm

Free jQuery eBook:

http://www.heronote.com/files/jQuery.htm

Comment by heronote — June 1, 2011

Leave a comment

You must be logged in to post a comment.