[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 
in API).

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!
ditto. +1
> 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 
news, etc.

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 mailing list