[Dojo-interest] Dojo Documentation: A Proposal

[Eugene Lazutkin]

+1.

Correspondence to the actual physical layout is crucial --- it should be
easy to find the code by the book, and visa versa.

We have to have a tutorial for each section and more in depth technical
documentation as well. It would be nice to integrate the API tool with
the technical documentation somehow.

On top of that it would be nice to have task-based "what's available"
sections in the form of a guide book, which directs people to relevant
parts of Dojo Core, Dijit, and DojoX.

Thanks,

Eugene

Daniel wrote:
> Hello,
> 
> I'd like to suggest a general plan for Dojo documentation. This is 
> intended as an eventual replacement of the Dojo Book. First, some notes:
> 
> - I hope that nobody is offended by my suggesting a major redesign. This 
> is just an idea, and I fully understand that a lot of work went into the 
> existing documentation and I intend no offence.
> 
> - Am I an expert? No, I'm not. But I do have some experience. I founded 
> the OpenOffice User Guide project and I'm one of its principal authors. 
> There I had the privilege to learn a lot from a highly recognized 
> technical editor. I am also a co-author of a published book on OpenOffice.
> 
> - Am I volunteering? Well, if (1) I manage to do my current project with 
> Dojo and (2) you can wait for mid-late January, then yes, I would be 
> willing to do some of the work. I'm also willing to write a style guide 
> including tips on how to write documentation. That's easy, since I'd 
> just adapt the one from the OpenOffice user guide.
> 
> 
> So, what is my proposal?
> 
> I think that Dojo is too broad to reasonably document in one single 
> book. Such a book would be either too limited, or too large. Either way, 
> users would find it difficult to learn from it. Instead, I propose three 
> different and independent books:
> 
> - Dojo Base: An Ajax Application Framework
> - Dijit: Graphical Applications with Dojo
> - DojoX: Dojo Extensions
> 
> Yes, this is based on the real layout of Dojo. This is a design feature.
> 
> Each book would be independent, and stand on its own. Specifically, the 
> Dijit book would not assume any existing knowledge of Dojo. Yes, this 
> will require some repetition, but the result will be well worth the price.
> 
> Each book would have two parts:
> 
> - Learning XYZ
> 
>    Tutorial-like style. It is task-based, and organized sequentially.
>    This is not a reference. The first chapter will always be called
>    "Getting Started". It starts with simpler concepts and builds up.
> 
>    One thing to remember is that a chapter must never be "how to use
>    this feature" but "how to accomplish this task". For example:
> 
>    BAD:  How to use layoutContainer
> 
>    GOOD: Control the visual layout of your application
>       (and the chapter would cover several tools relevant to layout,
>        not just layoutContainer).
> 
> 
> - XYZ Reference and Examples
> 
>    Reference style. One chapter for each component. Each chapter
>    has the following sections: Properties, Methods, Examples. The
>    existing Dojo tests would just be copy-pasted to serve as examples.
> 
> 
> Some notes:
> * Having a good reference in the book makes the tutorial-style component 
> easier to write (but no less important). For example, each chapter in 
> "Learning XYZ" could end with a section titled "Learn more" that links 
> to relevant reference chapters and some times future chapters in 
> "Learning XYZ".
> 
> * Experienced users still get the reference they need. That's important too.
> 
> * "DojoX" would need a different layout. DojoX is not coherent enough to 
> make a sensible "Learning DojoX" section. But this doesn't mean that 
> tutorial style reference should be ignored. Rather, I think we are 
> looking at something more like HOWTOs.
> 
> 
> So... that's my idea.
> 
> Any thoughts?
> 
> 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
>