[dojo-contributors] 1.1 overload

Dustin Machi 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 
>> dtk.org/developer/dijit).
>>     
>
> 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 
nobody remembers).  

> 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.

Dustin


> _______________________________________________
> dojo-contributors mailing list
> dojo-contributors at dojotoolkit.org
> http://turtle.dojotoolkit.org/mailman/listinfo/dojo-contributors
>
>   



More information about the dojo-contributors mailing list