improving dojotoolkit.org and dojo documentation
November 9th, 2007 by Dylan
Now that Dojo 1.0 has shipped, the community is putting a lot of effort into finishing the new web site, updating tutorials, improving documentation, examples, and demos. And fixing bugs of course.
Even with the new launch of the web site next week, we know there’s going to be a lot we can do better, and sometimes this feedback gets lost in the noise. Please let us know how we can do better, what you find to be most lacking or most needing improvement. We’re tired of being told our documentation sucks, so now that we have pretty solid source code documentation, and a pretty comprehensive online book, what else can we add to make your life easier while using Dojo?
Feel free to comment here, send us email, file a ticket in trac, etc. And of course, if there’s a demo, example, tutorial, or documentation that you’ve created that you’d like to contribute, or at least have us link to, please let us know!
Hi Dylan,
Things that can help to the programming community:
– a “printable” book
– a longer and less steep introduction to dojo
and of course, continue improving the documentation.
Miguel
A consolidated demo application similar to http://www.smartclient.com/index.jsp#_Welcome is desperately needed. Newbies have no idea what Dojo can do, and pointing them to test files, all located in separate folders, just makes Dojo look unprofessional.
Dylan:
How about JavaDocs-style docs?
An introduction to using the API docs is probably a good idea.
A cross-list of all dojo objects. An index of dojo objects, alpha sorted, to make it a little easier to find more info on specific objects.
One of the most confusing things about any toolkit, framework etc, is learning what’s native to the underlying language, and what’s provided by the higher layer tools. You might want to consider including native javascript objects in your docs; I’m not suggesting that you re-invent that wheel, but just something that indicates that the item in question is core javascript (not core dojo).
A cookbook would be nice, as well. Simple recipes that show basic tasks. My recollection is that a lot of the examples are not small, which is fine, but chunked, task-specific examples would help some users.
I think that a fair number (the majority??) of developers/programmers are visual learners. I’ve heard from fellow students that they wish that there were more diagrams in teaching materials. I’m not sure if that goes for docs as well, and I know that diagrams are tricky and can be time-consuming, but the adage that a picture is worth a kiloword is something to consider.
HTML linked code. So, in example code, objects are linked to the docs (or tooltips come up, etc).
Thanks for asking for comments, and thanks for your work with the Dojo Project.
Greg
Dojo online documentation is a joke!
IF not for IBM, I’d be learning a beneficial skill like jquery. Why does IBM make such awful decisions like selling off CD technology and DOJO?
Shawn,
You’re obviously entitled to your opinion, but the docs have been improving substantially and keep improving. How about some constructive feedback so we can keep focusing on making the docs better?
-Dylan