As an addendum to this proposal, I'd like to also outline some editorial guidelines in light of our existing docs:

* introductions are almost never necessary...
* ...but if a page really needs an intro -- say, because it's the first introduction to a particular name or area -- it should be 1 sentence at the most and should only set context. Leave discussions of how awesome things are to the (awesome) demos.
* unless there's a good reason to hide it, example code should be visible in the page. The CodeGlass demo viewer requires an extra click to see anything by default. Avoid it until this bug is fixed.
* avoid saying ambiguious things like "there is no right answer" or "there are many ways to do it". Present options as being best for one scenario or another by discussing tradeoffs or simply present one way of doing something. Using Dojo means having great tools that the the Right Thing out of the box, so present choices in a positive light.
* present high-performance options first
* move descriptions of advanced topics out to their own, clearly-marked pages
* put common operations first in explanatory documentation. Leave detailed discussion and examples of all possible options to API documentation
* if a topic does not fit cleanly under some other heading, make it a top-level discussion, e.g., Functional Programming in Dojo should be discussed as it's own article and not hidden under dojox.lang.functional and/or dojo.[map|filter|forEach|...]
* if a page is less than a couple of hundred words, consider folding it into another page
* discuss related topics on the same page, do not break them up into their own pages unless the content becomes so long as to make the page unweidly

Others? What am I forgetting?
On Feb 13, 2010, at 4:33 PM, Alex Russell wrote:
On Feb 13, 2010, at 3:48 PM, Tom Trenka wrote:

I think the best way is to create a rough outline for the guide,
publish it here (or somewhere where it can be viewed), and let people
take on bits and pieces of it. From there, Torrey will probably go
through and edit it and then it'd get published.

I'm pretty sure that one thing we want to avoid is the idea that the
website itself is functionally equivalent to the actual DTK project;
editing wiki docs and making sure the code has the doc comments is one
thing but the website is something else altogether.

That being said, definitely a rough outline of how the guide should be
structured would be a huge help.

Ok then, here's my rough proposal:

[ Dojo Quick Start ]

"The Basics" (first page, most people land here):

Blurb: Dojo is easy. How easy? This easy:

<page that includes Dojo from the CDN, shows dojo.ready, finds nodes, uses XHR to pull in new content, and animates>

Discussion:

* talk about dojo.query() FIRST
* examples of common dojo.NodeList methods
* discuss dojo.xhr, links to docs
* events with dojo.query().connect and dojo.connect()
* links, links, links

Big link to next page -->

"Debugging and Packages, And Awesome JavaScript Utilities"

* introduce djConfig, link to options
* talk about console.*
* introduce dojo.require()
- examples of requiring core functionality
- import extensions to dojo.NodeList
- import/use dojox.jq to show compatibility
- link to advanced topics, including "building your own packages" in the SDK quickstart
* examples, examples, examples

-->

"JavaScript Development Just Got Awesome"

* introduce class system
* functional programming with Dojo
* doh for testing
- in-browser
- command-line
* want more? See the SDK Quickstart

-->

[ Dojo SDK Quick Start ]

"Getting, Configuring, and Building the SDK"

* walkthrough of download (from current quickstart)

<example page that uses dojo from SDK>

* walkthrough of simple build

<upgrade example to point to new build>

Wasn't that easy? Just change one path!


-->

"Building Your Own Packages"

* show show filesystem layout

myapp/ver/js/dojo_sdk/
myapp/ver/js/myapp/

* example page using custom modules, myapp.*, djConfig mapping
* anatomy of custom module
dojo.require, dojo.provide()
sub-paths, module mapping
* recipe for svn:externals mapping of Dojo tagged releases

-->

"Custom Builds, Optimization, and CDNs"

* show a custom build file, show build using it
* update the example from the previous page to reference the build output
* show command line flags, what they do, how to point output to a different directory
* show how to pull in layers from the CDN and only serve custom layers locally

[ Dijit Quick Start Guide ]

"The Basics"

* How Easy Is Dijit? This easy:

<example that pulls in Dojo, Dijit, etc. from CDN, uses a non-default theme, does full-page layout, and has tabs...all programmatic>

(must load FAST when copied to user's machine)

* Fast prototyping with markup

<same example as above, but parseOnLoad: true and move to using markup-constructed widgets>

* What else can it do?
- examples of lots of widgets (feature explorer?)
- screenshots of themes, talk about how easy they are to use
* Enterprise ready
- screenshot of high-contrast, maybe links to a11y, i18n presentations?

-->


"Getting The Most out of Widgets"

* attr()
* creating/adding child widgets
* when to use startup()

<example code>

* using layouts to make building pages easier
* using sliders, selectors, form widgets in forms

"Popular Dijit Extensions: Charts and Grids"

* Awesome, powerful, easy:

<small programmatic demo pulling JSON data into a chart and a grid>

* Lots of data? No problem.

- discuss dojo.data APIs
- update previous example to use a different data store, show how easy it is
- links to documentation/examples for paginating data stores
* Common Grid options
- auto layout
- grids in content panes
- links to docs
* Enhanced Grid
* Advanced charting examples
- available types
- common options
- legends
* dojox.charting.DataChart

"Custom Widgets"

* simple CDN example without separate file using dojo.declare()
* inheriting from a Dijit
* show markup version of custom widget
* dojo.cache()
* point to SDK quickstart, discuss widget resources for builds

-->

"Where To Learn More"

links, links, links, links

What is it missing?

--
Alex Russell
slightlyoff at google.com
alex at dojotoolkit.org BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723

_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
--
Alex Russell
slightlyoff at google.com
alex at dojotoolkit.org BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723

Search Discussions

Discussion Posts

Previous

Follow ups

Related Discussions

Discussion Navigation
viewthread | post
posts ‹ prev | 4 of 8 | next ›
Discussion Overview
groupdojo-contributors @
categoriesdojo
postedFeb 13, '10 at 6:39p
activeFeb 14, '10 at 9:14p
posts8
users4
websitedojotoolkit.org

People

Translate

site design / logo © 2022 Grokbase