On Feb 14, 2010, at 9:28 AM, Tom Trenka wrote:
I like the outline; the only thing I'd be concerned about (and it's
not a huge concern) is that it covers a lot of material and could even
be an outline for a small "dojo for idiots" type book =)
There's a lot in Dojo. That the outline helps people get acquainted with the bits they'll need in the order they'll need them hardly seems like a bug. Right now there's no canonical place to go for most of this stuff.
I also agree with Dylan in that we need to address "coming from the
server side"; all too often we get questions on the mailing list about
how to integrate with JSPs and what not, and having at least some
examples of that would go a long ways. Agreed.
Last thing that might not be a bad idea is how to generate docs from
their own source code; I've been trying to set up the API tool (not
the static docs generated but the new one sitting at
http://api-staging.dojotoolkit.org ) so that its a fairly brainless
process to generate your own API docs, though there are still manual
steps that need to be done =( Nice thing about that tool is that I
think it's also a good demo for showing how to get a quick-and-dirty
Dijit-based app up and running within a PHP environment (bonus in my
book ;)).
I like the outline; the only thing I'd be concerned about (and it's
not a huge concern) is that it covers a lot of material and could even
be an outline for a small "dojo for idiots" type book =)
There's a lot in Dojo. That the outline helps people get acquainted with the bits they'll need in the order they'll need them hardly seems like a bug. Right now there's no canonical place to go for most of this stuff.
I also agree with Dylan in that we need to address "coming from the
server side"; all too often we get questions on the mailing list about
how to integrate with JSPs and what not, and having at least some
examples of that would go a long ways. Agreed.
Last thing that might not be a bad idea is how to generate docs from
their own source code; I've been trying to set up the API tool (not
the static docs generated but the new one sitting at
http://api-staging.dojotoolkit.org ) so that its a fairly brainless
process to generate your own API docs, though there are still manual
steps that need to be done =( Nice thing about that tool is that I
think it's also a good demo for showing how to get a quick-and-dirty
Dijit-based app up and running within a PHP environment (bonus in my
book ;)).
On Sun, Feb 14, 2010 at 8:56 AM, Dylan Schiemann wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
I'd also like to suggest an integration section (I added a todo list a
while back to docs on Dojo Campus)... basically how to get started with
Dojo based on which server-side environment or framework you are using.
It's somewhat orthogonal to this, but definitely helps users coming
from different backgrounds that are new to Dojo. Some of these could be
third-party resources, some should be our own, etc.
See http://docs.dojocampus.org/todo?highlight=%28todo%29 for more
details on what I was thinking.
Regards,
- -Dylan
Version: GnuPG v1.4.9 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkt4DysACgkQ1E2HcBNypM5bVQCeKGvvSp/Ww5/oNJRdJztOZGFR
UcMAniGxyZ5ePyKrINYS1nBzFYVmJcII
a7m
-----END PGP SIGNATURE-----
_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
_______________________________________________-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
I'd also like to suggest an integration section (I added a todo list a
while back to docs on Dojo Campus)... basically how to get started with
Dojo based on which server-side environment or framework you are using.
It's somewhat orthogonal to this, but definitely helps users coming
from different backgrounds that are new to Dojo. Some of these could be
third-party resources, some should be our own, etc.
See http://docs.dojocampus.org/todo?highlight=%28todo%29 for more
details on what I was thinking.
Regards,
- -Dylan
On 2/13/10 5:52 PM, Alex Russell wrote:
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?
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
-----BEGIN PGP SIGNATURE-----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:
[ 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
--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: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.
[ 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
_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
Version: GnuPG v1.4.9 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkt4DysACgkQ1E2HcBNypM5bVQCeKGvvSp/Ww5/oNJRdJztOZGFR
UcMAniGxyZ5ePyKrINYS1nBzFYVmJcII
a7m
-----END PGP SIGNATURE-----
_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
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
