Ajax Girl

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?

Source: Ajaxian
Original Article: http://ajaxian.com/archives/docs-for-dojo-prototype-others