[dojo-contributors] 1.1 overload
dmachi at sitepen.com
Thu May 1 08:20:54 EDT 2008
Bill Keese wrote:
>> The other thing that worries me w.r.t. the web (and I'm sure we repeat
>> this conversation every six months) is that most of the dojo information
>> on the web (the stuff that google points to) is hopelessly out of date,
>> including dojo.jot.com, manual.dojotoolkit.org, and even the online book
>> on dtk.org (plus also other sections on dtk.org too, ike
> PS: My original message might not have been clear...
> There are actually two issues. Deleting obsolete pages like
> dojo.jot.com is actually the simpler of the two. The harder (ie, more
> time-consuming) task is updating the online manual which I assume has
> gotten really out of date.
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. I'm
sure somethings are out of date but that is the nature of
documentation...it is going to get out of date. Search for any other
lib on the web that has multiple versions and has had documentation for
those versions, you will end up with different copies of it in google.
We could of course take down anything as soon as it is no longer valid
in trunk, but then that screws anyone that isn't caught up yet. I think
the better way to would be flag what is current and what is not perhaps
somewhat similar to the Django book.
Aside from the committer list on dojo.jot.com, I think we can just that
entire site down. We have been through it before (though apparently
> 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, 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.
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
maintain. 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.
> dojo-contributors mailing list
> dojo-contributors at dojotoolkit.org
More information about the dojo-contributors