Updated tech overview

Updated tech overview

Staged at:
http://to.dart-lang.appspot.com/docs/technical-overview/index.html

BUG=5274
Committed: ef54e2e

[sethladd, 2012-11-01 05:23:52]

Would really like to see more detail on the editor, dart2js, and pub. We spend a
lot of time about the language, but we now have much more.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:9: Dart is a class-based programming
language
How about:

"Dart helps developers scale from small scripts to large apps as they build
high-performance apps for the modern web. Dart compiles to JavaScript and
targets modern desktop and mobile browsers."

And then continue with "Developed with..."

And then a statement like "Dart is more than a language, with the project
shipping a productive editor, a package manager, libraries, and more."  Or
something.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:48: <h2> Key features </h2>
Maybe "Key features of the language" which then leaves room for "Key features of
the editor"

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:52: classes, optional types,
libraries, and tooling.
I'd also include isolates as being key.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:54: 
Maybe a note about "even though Dart is familiar, we took this opportunity to
clean up some problematic areas of other commons languages and introduce
features we like from other languages"

Examples:

- lexical scope
- method cascades
- optional params
- top level functions
- one-line functions
- multi-line strings
- string interpolation

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:67: Code can have static types.
Almost too "matter of fact". Can you talk about scalability here?

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:242: Here is what this code looks
like with a few types added
A more powerful example:

(before)

recalculate(origin, offset, estimate) { .. }

(after)

num recalculate(Point origin, num offset,
                {bool estimate:false}) {

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:274: For other modern browsers,
Please lead with this point (JavaScript compilation is critical factor)

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:318: window.alert('Clicked!');
Instead of window.alert, let's use:

query("#msg").text = "You clicked the button!"

and add an <output id="msg"></output> to the HTML

My main concern is not to show window.alert

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:401: Dart provides several libraries
we should also talk about unit tests, JSON, math, and more.

[Kathy Walrath, 2012-12-12 22:49:04]

ptal

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:9: Dart is a class-based programming
language
On 2012/11/01 05:23:52, sethladd wrote:
> How about:
> 
> "Dart helps developers scale from small scripts to large apps as they build
> high-performance apps for the modern web. Dart compiles to JavaScript and
> targets modern desktop and mobile browsers."
> 
> And then continue with "Developed with..."
> 
> And then a statement like "Dart is more than a language, with the project
> shipping a productive editor, a package manager, libraries, and more."  Or
> something.

Done. (But not exactly what you said. Please take a close look.)

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:48: <h2> Key features </h2>
On 2012/11/01 05:23:52, sethladd wrote:
> Maybe "Key features of the language" which then leaves room for "Key features
of
> the editor"

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:52: classes, optional types,
libraries, and tooling.
On 2012/11/01 05:23:52, sethladd wrote:
> I'd also include isolates as being key.

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:54: 
On 2012/11/01 05:23:52, sethladd wrote:
> Maybe a note about "even though Dart is familiar, we took this opportunity to
> clean up some problematic areas of other commons languages and introduce
> features we like from other languages"
> 
> Examples:
> 
> - lexical scope
> - method cascades
> - optional params
> - top level functions
> - one-line functions
> - multi-line strings
> - string interpolation

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:67: Code can have static types.
On 2012/11/01 05:23:52, sethladd wrote:
> Almost too "matter of fact". Can you talk about scalability here?

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:242: Here is what this code looks
like with a few types added
Since we're showing complete code here... What would this be recalculating?

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:274: For other modern browsers,
On 2012/11/01 05:23:52, sethladd wrote:
> Please lead with this point (JavaScript compilation is critical factor)

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:318: window.alert('Clicked!');
On 2012/11/01 05:23:52, sethladd wrote:
> Instead of window.alert, let's use:
> 
> query("#msg").text = "You clicked the button!"
> 
> and add an <output id="msg"></output> to the HTML
> 
> My main concern is not to show window.alert

Done.

https://chromiumcodereview.appspot.com/11366023/diff/1/src/site/docs/technica...
src/site/docs/technical-overview/index.html:401: Dart provides several libraries
On 2012/11/01 05:23:52, sethladd wrote:
> we should also talk about unit tests, JSON, math, and more.

Done.

[Kathy Walrath, 2012-12-14 01:13:46]

ptal

[Kathy Walrath, 2012-12-14 01:15:45]

Still to do:
- redo figure
- update/remove browser list
- confirm list of libraries we want to mention/describe

[Kathy Walrath, 2012-12-14 01:16:03]

On 2012/12/14 01:15:45, Kathy Walrath wrote:
> Still to do:
> - redo figure
> - update/remove browser list
> - confirm list of libraries we want to mention/describe

Oops, also:
- redo the web programming example to use web-ui

[sethladd, 2012-12-14 17:28:14]

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:20: The Dart open-source project
includes libraries, a package manager,
should we add "also includes" here? otherwise, I first read this as a complete
list. Also, you should add Web UI here.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:26: <strong>Note:</strong>
This should be a "project status" top-level section, I think. seems like a weird
place right here. Also, we'll be at M2 by the time we publish.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:59: <img src="images/perf-chart.png"
this chart will get out of date pretty fast. let's just link over to
/performance/

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:79: <li> <a href="#goals">Design
goals</a> </li>
Shouldn't Design Goals go before Language features?

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:100: <h2> Language features </h2>
More cool features to pick from:

http://programmers.stackexchange.com/questions/167070/differences-between-typ...

http://programmers.stackexchange.com/questions/164273/does-dart-have-any-usef...

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:455: <li><b>Dart Editor:</b> A
Dart-savvy editor that supports creating, modifying, running, and debugging Dart
apps</li>
savvy. I like it! :)

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:472: This JavaScript code works in
Chrome, Safari 5+, and Firefox 4+
probably more accurate to say:

latest Chrome, latest Safari, latest Firefox, and IE9+, plus mobile Safari and
Chrome for Android.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:494: Running an app is easy—a single
click—when you use Dart Editor.
I think you can remove this section

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:544: <img
src="images/DartEditor-debugger.png"
we should take high dpi screenshots for these. I can help.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:629: </dl>
Add "and more" ? How do we convey there are more libraries that just this? It's
not totally clear to me now.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:689: <a
href="https://plus.google.com/+dartlang">Dart on Google+</a> </li>
let's also mention the Dartisans community

https://plus.sandbox.google.com/communities/114566943291919232850

[sethladd, 2012-12-14 17:34:35]

https://chromiumcodereview.appspot.com/11366023/diff/22008/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/22008/src/site/docs/tech...
src/site/docs/technical-overview/index.html:125: <h3
id="lang-classes">Classes</h3>
what about just putting small examples for these features, right here? that way
it's more "show" and not just "tell"

[sethladd, 2012-12-14 17:39:00]

https://chromiumcodereview.appspot.com/11366023/diff/22008/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/22008/src/site/docs/tech...
src/site/docs/technical-overview/index.html:671: Other pages in the Dart
website,
This is really "Learning More" not "Get Involved"

https://chromiumcodereview.appspot.com/11366023/diff/22008/src/site/docs/tech...
src/site/docs/technical-overview/index.html:689: 
Let's add an explicit "Get Started" section with calls to action, like:

* Download the Editor
* Follow the tutorials
* Join the community

?

[Kathy Walrath, 2012-12-14 22:51:41]

ptal

I've incorporated many of your comments, but not all. (e.g. no examples in the
language feature section.) Do you think this is good enough, for now, or should
we make more changes before publishing this?

-k-

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:20: The Dart open-source project
includes libraries, a package manager,
> should we add "also includes" here? otherwise, I first read this as a complete
> list.

Done.

> Also, you should add Web UI here.

I didn't because it's not in the main Dart project. I did include it below.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:26: <strong>Note:</strong>
On 2012/12/14 17:28:14, sethladd wrote:
> This should be a "project status" top-level section, I think. seems like a
weird
> place right here. Also, we'll be at M2 by the time we publish.

I don't know... It seems like we ought to warn people early that it's still
changing. I did change it a bit and move it later, where it feeds naturally into
the performance paragraph.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:59: <img src="images/perf-chart.png"
On 2012/12/14 17:28:14, sethladd wrote:
> this chart will get out of date pretty fast. let's just link over to
> /performance/

Done.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:79: <li> <a href="#goals">Design
goals</a> </li>
On 2012/12/14 17:28:14, sethladd wrote:
> Shouldn't Design Goals go before Language features?

Yeah, probably. Especially since it uses bold font to emphasize words. :) Moved.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:100: <h2> Language features </h2>
On 2012/12/14 17:28:14, sethladd wrote:
> More cool features to pick from:
> 
>
http://programmers.stackexchange.com/questions/167070/differences-between-typ...
> 
>
http://programmers.stackexchange.com/questions/164273/does-dart-have-any-usef...

There are many, but this is already a laundry list...

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:472: This JavaScript code works in
Chrome, Safari 5+, and Firefox 4+
On 2012/12/14 17:28:14, sethladd wrote:
> probably more accurate to say:
> 
> latest Chrome, latest Safari, latest Firefox, and IE9+, plus mobile Safari and
> Chrome for Android.

Done.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:494: Running an app is easy—a single
click—when you use Dart Editor.
On 2012/12/14 17:28:14, sethladd wrote:
> I think you can remove this section

Done. To compensate, I added a bit more about launching to the following
section.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:544: <img
src="images/DartEditor-debugger.png"
On 2012/12/14 17:28:14, sethladd wrote:
> we should take high dpi screenshots for these. I can help.

If you could, that'd be great. Then you can show me how you did it.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:629: </dl>
On 2012/12/14 17:28:14, sethladd wrote:
> Add "and more" ? How do we convey there are more libraries that just this?
It's
> not totally clear to me now.

Done.

https://chromiumcodereview.appspot.com/11366023/diff/21001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:689: <a
href="https://plus.google.com/+dartlang">Dart on Google+</a> </li>
On 2012/12/14 17:28:14, sethladd wrote:
> let's also mention the Dartisans community
> 
> https://plus.sandbox.google.com/communities/114566943291919232850

Done.

[sethladd, 2012-12-16 22:23:03]

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:28: Additional open-source projects
and the Pub package manager
this confused me briefly. What about "Additional /dart/ open-source projects" or
"Additional libraries and tools from the Dart project"

Or...

A rich collection of Dart libraries can be found in Pub, a package manager for
Dart.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:41: Although the Dart language will
continue to change,
You say this, but then in the next paragraph, you say "the language has
stabilized"  Seems to contradict. Also, I don't think this needs to be a note.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:309: For example, here is a sample
of untyped code in Dart
Thoughts on a more compelling, or simple, example here?

What about:

function recalculate(origin, offset, estimate) {
  ...
}



num recalculate(Point origin, num offset, {bool estimate:false}) {
  ...
}

This sample makes it painfully obvious why type annotations are awesome.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:435: {% highlight html %}
for reference, there is a way to wrap this in {{ raw }} I think to avoid the
double escapes

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:438: The current time is:
{{'{{'}}currentTime}}
This would be more compelling if you rewrote the above example with Web UI

[Kathy Walrath, 2012-12-18 00:21:56]

ptal

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:28: Additional open-source projects
and the Pub package manager
On 2012/12/16 22:23:03, sethladd wrote:
> this confused me briefly. What about "Additional /dart/ open-source projects"
or
> "Additional libraries and tools from the Dart project"
> 
> Or...
> 
> A rich collection of Dart libraries can be found in Pub, a package manager for
> Dart.

Done.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:41: Although the Dart language will
continue to change,
On 2012/12/16 22:23:03, sethladd wrote:
> You say this, but then in the next paragraph, you say "the language has
> stabilized"  Seems to contradict. Also, I don't think this needs to be a note.

Done.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:309: For example, here is a sample
of untyped code in Dart
> function recalculate(origin, offset, estimate) {

You wouldn't really have 'function' here, would you?

> num recalculate(Point origin, num offset, {bool estimate:false}) {

You could do the optional argument without types, although it makes sense to
progress that way, so I'll try to explain that.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:435: {% highlight html %}
On 2012/12/16 22:23:03, sethladd wrote:
> for reference, there is a way to wrap this in {{ raw }} I think to avoid the
> double escapes

Done.

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:438: The current time is:
{{'{{'}}currentTime}}
On 2012/12/16 22:23:03, sethladd wrote:
> This would be more compelling if you rewrote the above example with Web UI

I couldn't see a way of using Web UI at this point without writing a bunch of
code that obscured the point I was trying to make.

[sethladd, 2012-12-18 00:31:45]

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
File src/site/docs/technical-overview/index.html (right):

https://chromiumcodereview.appspot.com/11366023/diff/33001/src/site/docs/tech...
src/site/docs/technical-overview/index.html:309: For example, here is a sample
of untyped code in Dart
Right, sorry, the first is JavaScript.

[sethladd, 2012-12-18 16:48:04]

lgtm