[dojo-contributors] 1.1 overload
dmachi at sitepen.com
Thu May 1 11:58:00 EDT 2008
Bill Keese wrote:
> Dustin Machi wrote:
>> While I'm sure the manual is out of date in some place, I don't think
>> "really out of date" is really a fair statement. If it is then we have
>> entirely failed to have any sort of 1.0 compat throughout the lib.
> Well, I suspect that at least the new methods/parameters aren't
> documented and the deprecated methods/parameters still are. Dijit has
> had a lot of churn since 0.9 and although we maintained backwards
> compatibility there are a lot of updates and deprecations.
> There's also been a ton of stuff added to dojox, like charting and new
> RPC layer (IIRC) that would be good to document.
> Plus, all the user comments attached to each page should be processed
Sure, I'm sure there are things wrong in it, but I think on the whole it
is more correct than it isn't. Failure to have new things documented
needs to be addressed of course (though in regards to RPC, its a dojox
module under development, and the standard dojo.rpc is documented and
still in core), but I would guess things that are deprecated still need
to be documentend and represented, but need to have a deprecated
label/marking associated with them instead of deleting them, right?
Also people do get the comments and reply to them most of the time I
think, though undoubtedly we could do better.
>> Aside from the committer list on dojo.jot.com, I think we can just take
>> [dojo.jot.com] down. We have been through it before (though apparently
>> nobody remembers).
> I could be wrong... I remember some parts being processed but I didn't
> think we transferred everything. Like for example those 0.4 release
> notes, or http://dojo.jot.com/WikiHome/tr2. Plus I notice that the
> dojo.jot.com FAQ (http://dojo.jot.com/FAQ) has a lot more entries the
> the FAQ on dojotoolkit.org (http://dojotoolkit.org/support/faq).
Well I think we went through and moved what we wanted. I know all of
the FAQ items were in at one point, but the FAQ itself has gone through
incarnations, so the differences aren't because of a lack of transfer
but more because of content changes/additions/subtractions. All that
said the terms could be pulled over if we want them. To be honest,
while I used to end up at jot frequently when I did searches, that
doesn't tend to be the case so much anymore.
>>> Having said that, there's a lot of redundancy between the online manual
>>> and other sites, specifically the examples on dojocampus and the
>>> auto-generated API guide, so maybe we should get rid of that info from
>>> the manual,
>> Well I don't think redundancy in documentation is bad at all, I would
>> argue that it is good..its not code. Admittedly it is more work to
> It's just that we've all been so busy making dojo great that I at least
> haven't had time to maintain the manual, and I'm worried that we won't
> have time in the coming months either.
Some we can address through cross linking, others we simply have to
update. I know some people update as they go. In general its not such
a big huge task as it used to be (when everything needed to be written
from scratch) if you do it as you make modifications. If you change the
whole system then try to bring the docs up to speed, its likely to not
get done quickly. Kind of like cleaning your closet :)
> >>although I'm reluctant to remove the API info from the
> >> manual until we can get the metatdata and infrastructure support so the
> >> auto-generated API guide can differentiate between protected and public
> >> methods, and also between initialization parameters/event
> >> handlers/normal methods/callbacks that the user should override.
>> In regard to the last portion of this statement, I'm guessing
>> some of that is going to be impossible since as a human being there are
>> several places that I cannot tell what I should do. I imaging having
>> the api tool figure it out will be a little more difficult. Furthermore
>> we have pretty much destroyed the meaning of _ on functions and
>> filenames or at least diluted it to the point where you can't
>> consistently apply some usage pattern.
> Well, we don't have to make the API tool figure out anything, we can
> just mark each parameter/method with keywords.
Ok. I was a bit harsh there, but I would still like to be able to
interpret the underscore char consistently. :P
I've been seeing a lot of positive feedback on our community efforts
both in terms of website/documentation but also in terms of support, so
I think we're on the right track, but we've got to continually improve
in all areas. While I understand some of the sentiment behind continual
changes on the website, I think its the wrong perspective to take. Each
time we improve things, there is less and less we have to change because
we are making gradual changes and are simply adapting to the times and
the needs of the various people interested in Dojo. It doesn't have to
be seen as something that is going to take away time from people
developing code since it is generally new people or people interested in
making those aspects of Dojo just as good as the toolkit, that are doing
that work. Since the data structures maintaining our book, api, etc are
generally working and don't need significant changes, the visual aspects
of that can easily adapt to our current and future needs and goals
without having to redo everything from scratch as we used to do. That
has been and will continue to be the focus and goal mine from an
infrastructure perspective, and I think that is consistent with the
goals of others from a documentation, support, and marketing perspective
More information about the dojo-contributors