[dojo-contributors] dojo-contributors Digest, Vol 50, Issue 3
Peter E Higgins
dante at dojotoolkit.org
Fri May 2 07:55:14 EDT 2008
Bill Keese wrote:
> Craig Riecke wrote:
>> This is all thought-provoking stuff. I feel bad about letting the
>> dandelions grow in the online book, so now that the Pragmatic Book's
>> done, am glad to hop back on the lawn mower and get going. You have no
>> idea how glad :-)
> By the way, I wasn't trying to point fingers at you. I was more saying
> that maintaining the book in it's current form requires a lot of effort
> from the community (in addition to the tremendous job you did basically
> writing the whole thing), and I'm not sure our community is up to
> maintaining everything in that book in addition to dojo campus and
> api.dojotoolkit.org, and of course all the great enhancements and bug
> fixes to the code itself.
Ye of little faith, Bill. The book obviously is a much harder target,
moving, more eyes, way larger... We also have the issue of maintaining a
dojo.js version on the site
and attempting to include live examples (something the explorer does
just fine, imho)
Everyone in the community who contributes is valued. If someone can
write words, but can't code worth a lick, they shouldn't be grouped into
the expectation of code submissions or technical docs. We should utilize
a) what people are good at and b) what people WANT to do to help.
Granted we can say "your help would best be served here ..." but like
anything, if you "give" someone a mundane job they don't whole-heartedly
"feel" like is doing something, they won't stick around. Embrace the
contributions and whatnot that come in, rather than worry about some
other aspect being "neglected". It just means we need more eyes, and
more people feeling good about what they are contributing.
I think the API pages will maintain themselves in the form of
automation. That said, we still deprerately need versioning in the book,
or at least a static copy of what jsdoc knows right at release time in
some portable format (xml/json) ... When that is in place, we can "just
update" inline docs, and know that prior versions were more accurate.
Campus is easy to maintain. It's aggregate, and we didn't start to try
and write it during 0.9 ... ;) That and it was never meant as a
replacement for the Book, just a different place for a different
audience with different needs. The cliff notes of Dojo? It spawned from
my desire to have a community-run learning center and comments from
Eugene about Javasciprt guru's ... it has become, imho, a vital aspect
of Dojo in a very short time.
We're going with the Field of Dreams method of Dojo: If you build it,
they will come. Or something along those lines, but the point is: Campus
draws attention, has all those little copy/pasteable code snippets
everyone wants to learn from (without sifting through the tests/
folders), provides great short concise articles on HOWTO (and to be
honest, most of the topics thus far are legacy and could go back to 0.9
I had hoped the Api comments would be ready to go, but Campus beat that
out. Now is the time to more directly link the two. "Want more about
dojo.style(), see: api link" and beyond the first "cookie", all the
"cookies" and good stuff would/should be as we planned, as comments in
the API pages (much like php.net) ...
>> Does anybody object to my coming up with a plan? Then we can get some
>> volunteers and stuff...
> +1 from me too!
> On a related subject, here's a philosophical question that pains me a
> bit: if I have some new information to write about, for example, Tree,
> when should I blog and when should I add to dojo campus instead? (Or
> when should it go in the book?)
I guess it depends on the information I would say. Anything covered in
Campus should have a home in the book already, so if it's a new API
feature or something, the book is the place for it. If you are wanting
to show off something that is really cool to you, or "has always been
there and no one seems to notice", a Cookie is the perfect place to
focus that thought, with links back to the relevant API and Book pages
to support/followup. I would say you should blog announcements, exciting
So for instance, lets say you "perfect Tree DnD" in trunk. I'd blog it
(either blog, or just update the release notes), update the bookpages,
and write a campus cookie, in that order. If you don't get past book
page, someone else might find it interesting enough to write a cookie.
The cookies are really just to show a user how to do a particular thing,
or talk about some particular functionality in more depth than release
notes or psuedo API example block ...
I'm very excited about the API comments, and hope that will in turn
suffice for the "Cookies", though Cookies are a different audience than
someone wanting to dig into API docs, so we need to continue on
saturating the interwebs with our knowledge to reach the most people,
which is my primary concern. As soon as I am able to say:
"http://api.dojotoolkit.org/dojo.addOnLoad" to random user in #dojo
instead of again going into a DomReady discussion, the world will be a
better place, and I will have more free time to write code :) Of course
the addOnLoad API page will have a link to a Campus Cookie talking about
using addOnLoad + parseOnLoad:false to make a windowed-preloader, and
the Cookie will in turn link back to both addOnLoad and djConfig API
pages, for completness.
More information about the dojo-contributors