[dojo-contributors] 1.1 overload

Dustin Machi 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 
> somehow.
>
>   
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 
>> maintain.
>>     
>
> 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 
as well.


Dustin




More information about the dojo-contributors mailing list