[Dojo-interest] Dojo Documentation: A Proposal

[Dylan Schiemann]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I think there's a lot of merit here what what you are saying, and for
the most part I agree.

While on this topic, I think the approach to "discoverability", and the
way that demos, tutorials, example, and API reference integrate with the
book(s) is key.  Basically we still need another major pass at the
information architecture of the site to help out with this, and this
suggestion seems to be a great way to make this happen.

Also, finally getting around to PDF versions of the book that look nice,
getting the API system done before the end of the year (and also
printable/downloadable), and getting some nice demos and tutorials in
place will go a long way.

This is not to say that we haven't made significant and awesome
improvements, just that we still have work to do.

Minor note to add: making reuse of content, when intentionally
duplicated, will help things from getting out of sync.  As noted in
recent discussions, we need to do more of this.

Regards,
- -Dylan

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
> 
> 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHVanO8nLgh/JJsxERAsw5AJ43stOp11ER/06FP3iuOrlsjO2TEQCZAVBo
ZhyUhk+qj7sD+YmDaHA5X/I=
=y92r
-----END PGP SIGNATURE-----