[dojo-contributors] dojo-contributors Digest, Vol 50, Issue 3
potatosculptor at gmail.com
Fri May 2 12:21:17 EDT 2008
The book, and the API docs need to be able to stand on their own. The
book is just that - you should be able to (literally or figuratively)
print and bind it and use it to walk your way through all the features
of the toolkit, and how to use them.
The campus augments that. Its a rich source of examples, that bubble
up stuff that is already documented in the book. Reciprocal links
btween the 2 benefit both - as well as links to the sitepen articles
and any other external dojo-related content. We do have to content
with link rot though - and the book is the only entity we have the
control over to backup, version, etc. I
I agree that we should periodically harvest the API comments. I do see
a problem if the API docs and the book (or any of the other resources)
start to vie with each other as being the authoratitive source on a
particular piece of dojo. Having to comb through the book, comments on
the book pages, the api docs and comments there is a bit much for what
should be essential documentation. Fine for getting context and
different perspectives on a feature though.
It seems like we'll start to need a diffinitive home for e.q.
dojo.query. Which page is the hub to which all articles, tutorials,
tips and corrections connect to?
I'd argue that if a dojocampus cookie finds itself linking over to a
sitepen blog post (or whatever) for further information on a feature -
that signals a gap in the book. We should be able to link to a central
dojotoolkit page that maintains a list of relevant resources -
including external ones. Yes, the sitepen articles on the Grid may
well be the best place to go to learn about the grid, but lets link to
a book/wiki page and let that direct me there.
Here's another way to think of it:
API docs: answer the What is in it? question
Book: answers the "what's it for?" question and "how do I use it?"
Campus: "how do /you/ use it?", "what's cool about it?"
On Fri, May 2, 2008 at 6:55 AM, Peter E Higgins <dante at dojotoolkit.org> wrote:
> 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