[Dojo-interest] Dojo Documentation: A Proposal

[Jon Sykes]

My only concern with this approach is that you spend a lot of time  
writing detailed documents for ABC, DEF, GHI and then the first person  
who reads them goes... But I need 123, why isn't that covered, these  
docs suck.

I'd rather have the time spent on core basic API description docs  
first and then add situational docs later.


On Dec 4, 2007, at 3:52 PM, Daniel wrote:

> Eugene Lazutkin wrote:
>>> I'm not sure I understand your suggestion. What do you mean by  
>>> "what's
>>> available" sections?
>>
>> "How can I do my layout with Dojo? There are layout widgets in Dijit:
>> abc, xyz, qwe. There are some advanced widgets in DojoX: asd, zxc,  
>> hjk.
>> There are some low-level components in Dojo Core: ..." Basically the
>> overview of "what's available to accomplish my task". Something that
>> crosses the boundaries of physical placement and gives you a
>> task-oriented guidance.
>
>
> That is very interesting. If it could be added in a non-confusing way,
> it could be quite useful. That said, if Dojo's layout tools really are
> spread out between Dojo Core, Dijit and DojoX, that's a bad sign for
> Dojo and suggests that my initial 3-book division may not be as  
> inspired
> as I thought.
>
> If the tools really are spread out the way you say, then maybe we  
> should
> investigate a different multi-book division. For example, the GUI book
> could be called "GUIs with Dojo" and the "Layout" chapter could talk
> about all the layout tools in Dojo Core, Dijit, and DojoX.
>
> A third alternative is that "generally" the tools are not scattered  
> like
> that, but "occasionally" there's a tool in a different section worth
> mentioning. In that case, I would suggest that those chapters  
> include a
> section called "You might also be interested in ... " which points to
> chapters in the other two books.
>
> So, a the standard chapter layout could be:
>
> * How to do XYZ with Dojo
>   - Introduction
>   - Blah
>   - Blah
>   - Blah
>   - Learn more
>     (links to reference pages for the widgets we used here)
>   - You might also be interested in...
>     (other widgets or tools, not discussed here, which might be
> relevant to what you are doing).
>
> How does that sound?
>
> Cheers,
> Daniel.
> _______________________________________________
> FAQ: http://dojotoolkit.org/support/faq
> Book: http://dojotoolkit.org/docs/book
> Forums: http://dojotoolkit.org/forum
> Dojo-interest at dojotoolkit.org
> http://dojotoolkit.org/mailman/listinfo/dojo-interest