Add asciidoc tutorial about using Polymer elements in Angular 2

Fixes vaadin/components-team-tasks#135

This change is

Review status: 0 of 5 files reviewed at latest revision, 4 unresolved discussions.

docs/tutorial.adoc, line 7 [r1] (raw file):

TODO: Link the resulting application code repository in this section when it gets published.

The following tutorial explains how to use Polymer elements in Angular 2 applications.

"...with the help of/using angular2-polymer" or something. I think the product should be mentioned in this sentence.
Would also change "The following" to "This".

docs/tutorial.adoc, line 9 [r1] (raw file):

The following tutorial explains how to use Polymer elements in Angular 2 applications.

For this purpose we are going to create an application similar to the Tour of Heroes example. Bun unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application would have a nice-looking mobile-first Material designed UI.

The first sentence assumes the reader already knows what Tour of Heroes example is, but it's not introduced until chapter 1.1

docs/tutorial.adoc, line 194 [r1] (raw file):

[TIP]
.Add bower_components to .gitignore

.git was removed in an earlier step so this isn't needed

docs/tutorial.adoc, line 208 [r1] (raw file):

=== Npm dependency

Alongside with bower dependencies, we also need to add one npm dependency to the project. `@vaadin/angular2-polymer` package adds support for Polymer elements in Angular component templates. Run this command to install the package and save the dependency in `package.json` at the same time:

"Angular 2"

Comments from Reviewable

Added some initial comments. Still continuing the review though.
Previously, platosha (Anton Platonov) wrote…
> #### Add asciidoc tutorial about using Polymer elements in Angular 2
>
> Fixes vaadin/components-team-tasks#135
>
>
>

Review status: 0 of 5 files reviewed at latest revision, 12 unresolved discussions.

docs/tutorial.adoc, line 9 [r1] (raw file):

The following tutorial explains how to use Polymer elements in Angular 2 applications.

For this purpose we are going to create an application similar to the Tour of Heroes example. Bun unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application would have a nice-looking mobile-first Material designed UI.

I think "will have" might sound more confident than "would have". :smile:

docs/tutorial.adoc, line 19 [r1] (raw file):

=== The end result

In our heroes management application there would be two UI screens. This is the first screen with the list of all heroes made with Vaadin Grid of https://vaadin.com/elements[Vaadin Elements]:

Also here, maybe replace the "would" with "will".

docs/tutorial.adoc, line 151 [r1] (raw file):

[source,bash]
----
ls bower_components

I know we live in a world of OSX, but maybe some Windows users might be a bit confused with this. Or does ls nowadays also work on Windows command prompt?

docs/tutorial.adoc, line 232 [r1] (raw file):

    <!-- Polyfills -->
    <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
    <script src="node_modules/es6-shim/es6-shim.min.js"></script>

The quickstart has changed and es6-shim is no longer a dependency there. Should update this also.

docs/tutorial.adoc, line 300 [r1] (raw file):

Style changes::
Polymer elements come with nice builtin styles in the way of Material Desing. Angular 2 also provides style encapsulation mechanisms for our application components.

Typo – "Desing"

docs/tutorial.adoc, line 308 [r1] (raw file):

[TIP]
====
Instead of feaguring out the exact rules and values for the body style, here we import and reuse CSS mixins and CSS custom properties declared in `iron-flex-layout` and `paper-styles`.

Typo – "feaguring"

docs/tutorial.adoc, line 315 [r1] (raw file):

When using custom CSS mixins and custom CSS properties in your main document styles, wrap your styles inside `<style is="custom-style"></style>` tag.

See https://www.polymer-project.org/1.0/docs/devguide/styling.html[Styling section of the Polymer Developer Guide] for more information on styling Polymer lements and the document, custom CSS mixins and properties usage and limitations.

Typo – "lements"

docs/tutorial.adoc, line 341 [r1] (raw file):

After the previous step we have some Polymer elements imported in `index.html` of our application. In this step we are going to use them to create an application layout with a toolbar in `AppComponent`.

=== Updating SystemJS configuration

The SystemJS configuration seems to be changed a bit in the quickstart recently. Should probably update to the latest one.

Comments from Reviewable

docs/tutorial.adoc, line 325 [r1] (raw file):

Duplicated fetch of the same file is prevented in HTML Imports by checking the file location.

For example, in our tutorial application, we:

The first two bullets continue the sentence fine but the last two don't.

Comments from Reviewable

Reviewed 5 of 5 files at r1.
Review status: all files reviewed at latest revision, 16 unresolved discussions.

docs/tutorial.adoc, line 469 [r1] (raw file):

`paper-scroll-header-panel`:: Adds a scrollable container for the application contents. Also automatically detects `paper-toolbar` in the contents and places it above the scrollable container.

`paper-toolbar`:: Provides a toolbar wrapper styled in a way of Material Desing. Uses default theme from `paper-styles`.

Typo – "Desing"

docs/tutorial.adoc, line 675 [r1] (raw file):

== Hero editor and routing

Previosly we added the heroes list in our application. In this step we are going to add the editing feature. After that, the user should be able to navigate to the hero details by clicking a row in the heroes list, edit the details and get back to the list with the back button in the toolbar.

Typo – "Previosly"

docs/tutorial.adoc, line 896 [r1] (raw file):

Here are the UX-related changes to AppComponent explained.

==== Dynamic toolbar title

At this point I would have hoped to also see these nice touches in action, but adding the selection to the grid is done after this chapter. Maybe flip the order of these chapters ?

Comments from Reviewable

Looks like the app.component.spec.ts is giving a compilation error after the tutorial changes the AppComponent constructor. Maybe we should instruct to just delete the test?
Previously, tehapo (Teemu Pöntelin) wrote…
> Added some initial comments. Still continuing the review though.

Review status: all files reviewed at latest revision, 16 unresolved discussions.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 16 unresolved discussions.

docs/tutorial.adoc, line 7 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> "...with the help of/using angular2-polymer" or something. I think the product should be mentioned in this sentence.
>
> Would also change "The following" to "This".

Done.

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> I think "will have" might sound more confident than "would have". :smile:

Done.

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> The first sentence assumes the reader already knows what Tour of Heroes example is, but it's not introduced until chapter 1.1

I don’t think it is an issue. The reader not familiar with the Tour of Heroes doesn’t really miss any meaning of this paragraph.
Linked the tour here as well, though.

docs/tutorial.adoc, line 19 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Also here, maybe replace the "would" with "will".

Done.

docs/tutorial.adoc, line 151 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> I know we live in a world of OSX, but maybe some Windows users might be a bit confused with this. Or does `ls` nowadays also work on Windows command prompt?

Good point, `ls` doesn’t work on windows.
Reformulated without an explicit command given.

docs/tutorial.adoc, line 194 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> .git was removed in an earlier step so this isn't needed

That is true, but the .gitignore file stays here. It could be taken in use eventually, so it does make sense to update it.
Also I have a strong opinion that it is worth at least to inform the developers about that there is a such a folder to be excluded from version control.
This section is supplementary for the tutorial, it is not a required step, but an optional tip. That is why it is wrapped inside the “Tip” admonition.
This is done with the Quickstart README in mind, which also contains an optional step of creating git repository.

docs/tutorial.adoc, line 208 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> "Angular 2"

Done.

docs/tutorial.adoc, line 300 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Typo – "Desing"

Done.

docs/tutorial.adoc, line 308 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Typo – "feaguring"

Done.

docs/tutorial.adoc, line 315 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Typo – "lements"

Done.

docs/tutorial.adoc, line 325 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> The first two bullets continue the sentence fine but the last two don't.

Corrected. Now all bullets contain one or more separate sentences.

docs/tutorial.adoc, line 469 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Typo – "Desing"

Done.

docs/tutorial.adoc, line 675 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> Typo – "Previosly"

Done.

docs/tutorial.adoc, line 896 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> At this point I would have hoped to also see these nice touches in action, but adding the selection to the grid is done after this chapter. Maybe flip the order of these chapters ?

Right, the UX-related changes are not that important as completing the functionality. Moved this chapter to the last place.

Comments from Reviewable

Reviewed 1 of 1 files at r2.
Review status: all files reviewed at latest revision, 7 unresolved discussions.

Comments from Reviewable

Review status: all files reviewed at latest revision, 37 unresolved discussions.

docs/tutorial.adoc, line 9 [r2] (raw file):

This tutorial explains how to use Polymer elements in Angular 2 applications with the help of the `@vaadin/angular2-polymer` directives.

For this purpose we are going to create a staff management application similar to the https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] example. Bun unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.

Bun -> But

docs/tutorial.adoc, line 11 [r2] (raw file):

For this purpose we are going to create a staff management application similar to the https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] example. Bun unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.

=== The start point

Capitalise all titles. Also I think we should insert ID's for them

docs/tutorial.adoc, line 15 [r2] (raw file):

This tutorial is based on the https://angular.io/docs/ts/latest/quickstart.html[Angular 2 5 min QuickStart] and the https://angular.io/docs/ts/latest/tutorial/[Angular 2 Tour of Heroes]. We are going to start from the empty application source from the https://angular.io/docs/ts/latest/quickstart.html[QuickStart repository].

If you are not yet familiar with Angular 2, please walk through the Angular 2 QuickStart and the Tour of Heroes first. In this tutorial we are going to skip the explanations that are already given in the Angular 2 tutorials.

tutorials -> tutorial, or otherwise you should remove the

docs/tutorial.adoc, line 25 [r2] (raw file):

image::img/heroes-list-default.png[width="432",height="644"]

By clicking a grid row, the user can open the second screen, the hero detail editor made using Paper Input and Vaadin DatePicker:

I guess you need a preposition 'by clicking on  a grid row'
Also I would simplify the sentence:
By clicking on a grid row, the user can open the hero detail editor, made using Paper Input, and Vaadin DatePicker:

docs/tutorial.adoc, line 31 [r2] (raw file):

image::img/hero-detail.png[width="432",height="644"]

Both screens have a context-sensitive toolbar at the top with the title and the optional back icon button.

I miss a couple of comma : 'at the top, with the title, and ...'

docs/tutorial.adoc, line 35 [r2] (raw file):

== Creating project

This tutorial is based on the Angular 2 QuickStart TypeScript source code. In this step, we create new project on top of the QuickStart source code.

a new project

docs/tutorial.adoc, line 59 [r2] (raw file):

----

=== Starting from QuickStart ZIP package

Note that this title is partially capitalised (Package)

docs/tutorial.adoc, line 67 [r2] (raw file):

Install npm dependencies:

[source,bash]

[source,bash] is not valid , you should mark syntaxes by:
[subs="normal"]
[prompt]#$# [command]#npm# install

docs/tutorial.adoc, line 72 [r2] (raw file):

----

At this point you should be able to compile the TypeScript source code of the application and launch the development server. Let’s start the server to verify:

It sounds better to me:
At this point you should be able to compile TypeScript source code, and launch the development server.

docs/tutorial.adoc, line 83 [r2] (raw file):

[TIP]
====
See the https://github.com/angular/quickstart/blob/master/README.md[QuickStart README] for more information about creating a new project and other useful npm commands.

npm -> [command]#npm#

docs/tutorial.adoc, line 88 [r2] (raw file):

== Adding and installing dependencies

After the previous step, we have an empty Angular 2 application source with all the Angular dependencies installed. In this step we are going to add Polymer with some elements as dependencies to our application and install them.

In this step, we are going to add the Polymer library, and some elements, as dependencies of our application,  and install them.

docs/tutorial.adoc, line 90 [r2] (raw file):

After the previous step, we have an empty Angular 2 application source with all the Angular dependencies installed. In this step we are going to add Polymer with some elements as dependencies to our application and install them.

Vaadin Elements and other Polymer elements are mainly distributed through http://bower.io/[Bower]. In this step we are going to use Bower to declare and install our element dependencies.

I think you can replace our elements dependencies by then

docs/tutorial.adoc, line 96 [r2] (raw file):

[IMPORTANT]
====
You should install Bower before we start using it. Use npm to install Bower with this command:

npm -> [command]#npm#

docs/tutorial.adoc, line 98 [r2] (raw file):

You should install Bower before we start using it. Use npm to install Bower with this command:

[source,bash]

Use [subs="normal"] as I described above

docs/tutorial.adoc, line 146 [r2] (raw file):

----

After that, in your project root you should have `bower_components` directory with all elements declared by bower.json together with the elements’ requirements. List contents of the `bower_components` directory to verify that, it should contain these subdirectories:

bower_components -> the bower_components
declared by -> declared in the [filename]#bower.json#,  (note the comma)
List contents -> List the contents
bower_components -> [filename]#bower_components#

docs/tutorial.adoc, line 190 [r2] (raw file):

.Add bower_components to .gitignore
====
It is ususally a good practice to exclude external dependencies from your source control. Angular 2 QuickStart source code already contains `.gitignore` file, which excludes `node_modules` directory with npm dependencies from git repository of your application.

contains a [filename]#.gitignore#
also the node_modules

docs/tutorial.adoc, line 192 [r2] (raw file):

It is ususally a good practice to exclude external dependencies from your source control. Angular 2 QuickStart source code already contains `.gitignore` file, which excludes `node_modules` directory with npm dependencies from git repository of your application.

Please add the following line to the `.gitignore` file to also prevent bower dependencies from being tracked by your source control:

add [filename] mark

docs/tutorial.adoc, line 202 [r2] (raw file):

=== Npm dependency

Alongside with bower dependencies, we also need to add one npm dependency to the project. `@vaadin/angular2-polymer` package adds support for Polymer elements in Angular 2 component templates. Run this command to install the package and save the dependency in `package.json` at the same time:

I would mark npm with [command]#npm# or capitalise it instead

docs/tutorial.adoc, line 274 [r2] (raw file):

Doctype declaration::
We added `<!DOCTYPE html>` declaration in the first line of the HTML file. It switches document to use Standards mode, as required by the internals of `vaadin-grid`.

Add 'the' -> the doctype declaration ...

docs/tutorial.adoc, line 277 [r2] (raw file):

webcomponentsjs-lite.min.js polyfills::
The technology stack behind Web Components (namely, HTML Imports, Shadow DOM and Custom Elements) is not yet natively supported in all browses. We added webcomponentsjs-lite.js set of polyfills that enables using Web Components in browsers that lack native support.

This sounds better to me. I don't think the word set adds any extra info.
We added the [filename]#webcomponentsjs-lite.js# polyfill

docs/tutorial.adoc, line 280 [r2] (raw file):

Importing Polymer elements::
We added imports of Polymer elements that we are going to use in our application to the head section of `index.html`.

[filename]##

docs/tutorial.adoc, line 283 [r2] (raw file):

SystemJS app import change::
In some browsers, HTML Imports are loaded asynchronously. But we need them to be completely loaded before we import our Angular application. Hence we wrapped `System.import('app')...` call in the listener callback of the `WebComponentsReady` event, which is fired by the polyfill after all imports are loaded and elements have been registered.

[eventname]##

docs/tutorial.adoc, line 288 [r2] (raw file):

.Load order
====
The order of loading Polymer elements and the rest of the Angular application code does matter. It is required to have Polymer elements loaded and registered before importing the Angular application. `@vaadin/angular2-polymer` package strictly depends on that.

In core we mark this as
@vaadin/angular2-polymer

docs/tutorial.adoc, line 295 [r2] (raw file):

Polymer elements come with nice builtin styles in the way of Material Design. Angular 2 also provides style encapsulation mechanisms for our application components.
+
So the global styles are not needed anymore. Therefore we removed the `styles.css` external stylesheet and replaced it with `iron-flex-layout` and `paper-styles` style mixins imports and one embedded global style rule for body.

[filename]#styles.css#
[elementname]#iron-flex-layout# [elementname]#paper-styles#

docs/tutorial.adoc, line 297 [r2] (raw file):

So the global styles are not needed anymore. Therefore we removed the `styles.css` external stylesheet and replaced it with `iron-flex-layout` and `paper-styles` style mixins imports and one embedded global style rule for body.
+
The body style is the only global style that remains in our application. We need it to stretch the body container to occupy full height of the browser viewport, and also to specity default font styles and line height, default background and text colors.

It's difficult to read to me, it might be:
to occupy the full height of the browser viewport, and also to specify default font styles, line height, background, and text colours.
note also a couple of typos fixed

docs/tutorial.adoc, line 301 [r2] (raw file):

[TIP]
====
Instead of figuring out the exact rules and values for the body style, here we import and reuse CSS mixins and CSS custom properties declared in `iron-flex-layout` and `paper-styles`.

Use [elementname]##

docs/tutorial.adoc, line 306 [r2] (raw file):

[IMPORTANT]
====
When using custom CSS mixins and custom CSS properties in your main document styles, wrap your styles inside `<style is="custom-style"></style>` tag.

Article: inside a ...

docs/tutorial.adoc, line 308 [r2] (raw file):

When using custom CSS mixins and custom CSS properties in your main document styles, wrap your styles inside `<style is="custom-style"></style>` tag.

See https://www.polymer-project.org/1.0/docs/devguide/styling.html[Styling section of the Polymer Developer Guide] for more information on styling Polymer elements and the document, custom CSS mixins and properties usage and limitations.

See the styling ...

docs/tutorial.adoc, line 311 [r2] (raw file):

====

Delete `styles.css` file from your project directory since it is no longer in use.

[filename]##

docs/tutorial.adoc, line 320 [r2] (raw file):

For example, in our tutorial application:

* We have `<link rel="import" href="bower_components/iron-flex-layout/iron-flex-layout.html">` in our `index.html` file.

replace all filename occurrences  with proper [filename]##

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 43 unresolved discussions.

docs/tutorial.adoc, line 314 [r2] (raw file):

[NOTE]
.Duplicated imports handling

IMO, this information about imports is too extensive for a newbie. I don't thing she wants to dive into components to see what they import, etc. I would remove all this block.
I just would said that duplicated imports loading are prevented in browser side because of the specification.

docs/tutorial.adoc, line 359 [r2] (raw file):

----

Here is how your `systemjs.config.js` should look like after the change:

I think it's not relevant to copy and paste all the systemjs file. They are angular 2 developers so they should be used to this already

docs/tutorial.adoc, line 450 [r2] (raw file):

----

Save changes and launch the development server to see the results in your browser. After loading, your application have this look:

'should have' or 'has'

docs/tutorial.adoc, line 456 [r2] (raw file):

image::img/app-layout.png[width="432",height="644"]

Now your application has a layout made by using `app-header-layout`, `app-header` and `app-toolbar`.

[elementname]##

docs/tutorial.adoc, line 469 [r2] (raw file):

.app-layout elements are design-agnostic
====
Polymer elements from `app-layout` set, including `app-toolbar` that we use, are design-agnostic. They do not enforce have Material Design look by default, though still support it. Therefore we need to adjust `app-toolbar` styles a bit.

from the [elementname]#app-layout# set, ....
remove thought still support it (does not add extra info)
[elementname]#app-toolbar#

docs/tutorial.adoc, line 471 [r2] (raw file):

Polymer elements from `app-layout` set, including `app-toolbar` that we use, are design-agnostic. They do not enforce have Material Design look by default, though still support it. Therefore we need to adjust `app-toolbar` styles a bit.

Therefore we added color rules for the `app-toolbar` in the styles of the `AppComponent`. We reuse the color values of default theme from `paper-styles`.

I don't understand this block at all, first the therefore seems repetitive, second the explication is a bit messy. It didn't help me to follow the tutorial, probably you can remove it.

Comments from Reviewable

@tehapo Added instructions for removing tests.
Previously, tehapo (Teemu Pöntelin) wrote…
> Looks like the `app.component.spec.ts` is giving a compilation error after the tutorial changes the `AppComponent` constructor. Maybe we should instruct to just delete the test?

Review status: 4 of 5 files reviewed at latest revision, 43 unresolved discussions.

docs/tutorial.adoc, line 232 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> The quickstart has changed and es6-shim is no longer a dependency there. Should update this also.

Done.

docs/tutorial.adoc, line 341 [r1] (raw file):
Previously, tehapo (Teemu Pöntelin) wrote…
> The SystemJS configuration seems to be changed a bit in the quickstart recently. Should probably update to the latest one.

Done.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 48 unresolved discussions.

docs/tutorial.adoc, line 479 [r2] (raw file):

.PolymerElement directives
====
In order to enable all features of Polymer elements used inside your Angular component templates, remember to import `PolymerElement` in the component file and add `PolymerElement('element-name')` line for each Polymer element you use to the `directives` array of your component metadata.

[classname]#PolymerElement#

docs/tutorial.adoc, line 484 [r2] (raw file):

== List heroes with Vaadin Grid

In the previous step we added the application layout with `app-layout` elements. Next we are going add actual application content. Our plan is to use Vaadin Grid to list Heroes.

[elementname]##

docs/tutorial.adoc, line 496 [r2] (raw file):

=== Hero class

Let us start with creating the `Hero` class. Add `app/hero.ts` file with the following contents:

[classname]##  and [filename]##

docs/tutorial.adoc, line 508 [r2] (raw file):

----

Unlike in Angular 2 Tour of Heroes, in our application we are about to store and expose birthday of each hero for the user. Here we add `birthday: string;` property to our `Hero` class.

[classname]#Hero#

docs/tutorial.adoc, line 513 [r2] (raw file):

.Using strings to store dates
====
Why are we using tye `string` type and not `Date` to store dates? There are two reasons:

type -> type
probably string could be better in a [propertyname]##
[classname]#Date#

Comments from Reviewable

docs/tutorial.adoc, line 450 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> 'should have' or 'has'

Also, in my case it looked like this instead https://www.dropbox.com/s/f943sn403jd8eut/Screenshot%202016-05-24%2014.05.45.png?dl=0
var(--primary-color) doesn't compile to a value

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 50 unresolved discussions.

docs/tutorial.adoc, line 343 [r1] (raw file):

=== Updating SystemJS configuration

For using Polymer elements in our Angular components we need to import `PolymerElement` directives from `@vaadin/angular2-polymer`. Thus we need to make the module loader (SystemJS, in our case) aware of how to load the `@vaadin/angular2-polymer` package.

"Angular 2"

docs/tutorial.adoc, line 510 [r1] (raw file):

Why are we using tye `string` type and not `Date` to store dates? There are two reasons:

. Builtin JavaScript `Date` type is always stored as a timestamp, so it always contains the exact time information. This is not only redundant, but also harder to use then a plain string in case of storing just a date. It requires extra care about the correct time and timezone when storing the value and displaying it to the user, otherwise we might get incorrect dates because of timezone mismatches.

typo "harder to use than"

docs/tutorial.adoc, line 153 [r3] (raw file):

----

This file declares all bower dependencies for our application. Now install them with this command:

bower -> Bower
This is mistyped in few other places as well

Comments from Reviewable

docs/tutorial.adoc, line 450 [r2] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> Also, in my case it looked like this instead https://www.dropbox.com/s/f943sn403jd8eut/Screenshot%202016-05-24%2014.05.45.png?dl=0
>
> var(--primary-color) doesn't compile to a value

Nevermind, wrong branch :)

Comments from Reviewable

docs/tutorial.adoc, line 484 [r3] (raw file):

.app-layout elements are design-agnostic
====
Polymer elements from `app-layout` set, including `app-toolbar` that we use, are design-agnostic. They do not enforce have Material Design look by default, though still support it. Therefore we need to adjust `app-toolbar` styles a bit.

"..not enforce have..."

Comments from Reviewable

docs/tutorial.adoc, line 849 [r3] (raw file):

  directives: [
    ROUTER_DIRECTIVES,
    PolymerElement('paper-scroll-header-panel'),

These were missed while switching to app-layout

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 52 unresolved discussions.

docs/tutorial.adoc, line 343 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> "Angular 2"

Done.

docs/tutorial.adoc, line 510 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> typo "harder to use than"

Done.

docs/tutorial.adoc, line 288 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> In core we mark this as
>
> @vaadin/angular2-polymer

Can not understand your suggestion here.
I marked the first mention of @vaadin/angular2-polymer with a link and [literal] class, all the other mentions are just inside the code marks. This is how we have it in the core angular2 guide.

docs/tutorial.adoc, line 295 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [filename]#styles.css#
> [elementname]#iron-flex-layout# [elementname]#paper-styles#

Done.

docs/tutorial.adoc, line 301 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Use [elementname]##

Done.

docs/tutorial.adoc, line 306 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Article: inside a ...

Done.

docs/tutorial.adoc, line 308 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> See the styling ...

Done.

docs/tutorial.adoc, line 311 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [filename]##

Done.

docs/tutorial.adoc, line 314 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> IMO, this information about imports is too extensive for a newbie. I don't thing she wants to dive into components to see what they import, etc. I would remove all this block.
> I just would said that duplicated imports loading are prevented in browser side because of the specification.

Done.

docs/tutorial.adoc, line 320 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> replace all filename occurrences  with proper [filename]##

Done.

docs/tutorial.adoc, line 359 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I think it's not relevant to copy and paste all the systemjs file. They are angular 2 developers so they should be used to this already

Well, not having the complete source code listed in the tutorial might confuse the newcomers in Angular 2 development. Also, Angular tutorials have the complete source of all files.
Decided to remove the short changes listing instead of the complete source. I already described these changes in the paragraph above.

docs/tutorial.adoc, line 450 [r2] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> Nevermind, wrong branch :)

Done.

docs/tutorial.adoc, line 456 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [elementname]##

Done.

docs/tutorial.adoc, line 469 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> from the [elementname]#app-layout# set, ....
> remove thought still support it (does not add extra info)
> [elementname]#app-toolbar#

Done.

docs/tutorial.adoc, line 479 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [classname]#PolymerElement#

Done.

docs/tutorial.adoc, line 484 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [elementname]##

Done.

docs/tutorial.adoc, line 496 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [classname]##  and [filename]##

Done.

docs/tutorial.adoc, line 508 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [classname]#Hero#

Done.

docs/tutorial.adoc, line 513 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> type -> type
> probably string could be better in a [propertyname]##
> [classname]#Date#

Done.

docs/tutorial.adoc, line 849 [r3] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> These were missed while switching to app-layout

Done.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 52 unresolved discussions.

docs/tutorial.adoc, line 9 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Bun -> But

Done.

docs/tutorial.adoc, line 11 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Capitalise all titles. Also I think we should insert ID's for them

Done.

docs/tutorial.adoc, line 15 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> tutorials -> tutorial, or otherwise you should remove `the`

Done.

docs/tutorial.adoc, line 25 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I guess you need a preposition 'by clicking on  a grid row'
> Also I would simplify the sentence:
>
> By clicking on a grid row, the user can open the hero detail editor, made using Paper Input, and Vaadin DatePicker:

Done.

docs/tutorial.adoc, line 31 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I miss a couple of comma : 'at the top, with the title, and ...'

This amount of commas looks too high for me. Added just one for now.

docs/tutorial.adoc, line 35 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> a new project

Done.

docs/tutorial.adoc, line 59 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Note that this title is partially capitalised (Package)

Done.

docs/tutorial.adoc, line 67 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [source,bash] is not valid , you should mark syntaxes by:
>
>
> [subs="normal"]
> ----
> [prompt]#$# [command]#npm# install

Done.

docs/tutorial.adoc, line 72 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> It sounds better to me:
>
> At this point you should be able to compile TypeScript source code, and launch the development server.
>

Done.

docs/tutorial.adoc, line 83 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> npm -> [command]#npm#

Done.

docs/tutorial.adoc, line 88 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> In this step, we are going to add the Polymer library, and some elements, as dependencies of our application,  and install them.

Done.

docs/tutorial.adoc, line 90 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I think you can replace `our elements dependencies` by `then`

Done.

docs/tutorial.adoc, line 96 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> npm -> [command]#npm#

Done.

docs/tutorial.adoc, line 98 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Use [subs="normal"] as I described above

Done.

docs/tutorial.adoc, line 146 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> bower_components -> the bower_components
> declared by -> declared in the [filename]#bower.json#,  (note the comma)
> List contents -> List the contents
> bower_components -> [filename]#bower_components#

Done.

docs/tutorial.adoc, line 190 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> contains a [filename]#.gitignore#
> also the node_modules

Done.

docs/tutorial.adoc, line 192 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> add [filename] mark

Done.

docs/tutorial.adoc, line 202 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I would mark npm with [command]#npm# or capitalise it instead

There is no npm command in this line.

docs/tutorial.adoc, line 274 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> Add 'the' -> the doctype declaration ...

Done.

docs/tutorial.adoc, line 277 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> This sounds better to me. I don't think the word set adds any extra info.
> We added the [filename]#webcomponentsjs-lite.js# polyfill

Done.

docs/tutorial.adoc, line 280 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [filename]##

Done.

docs/tutorial.adoc, line 283 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> [eventname]##

Done.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 52 unresolved discussions.

docs/tutorial.adoc, line 297 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> It's difficult to read to me, it might be:
>
> to occupy the full height of the browser viewport, and also to specify default font styles, line height, background, and text colours.
>
> note also a couple of typos fixed

Done.

docs/tutorial.adoc, line 471 [r2] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> I don't understand this block at all, first the therefore seems repetitive, second the explication is a bit messy. It didn't help me to follow the tutorial, probably you can remove it.

Well, this block is a side-note explanation of the style changes. Would prefer to leave it here. The elements should be styled already, so why do we apply additional styles on them? I think, the reasons have to be mentioned.

docs/tutorial.adoc, line 153 [r3] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> bower -> Bower
> This is mistyped in few other places as well

Done.

docs/tutorial.adoc, line 484 [r3] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> "..not enforce have..."

Done.

Comments from Reviewable

@magi42 please review this tutorial
Previously, platosha (Anton Platonov) wrote…
> @tehapo Added instructions for removing tests.

Review status: 4 of 5 files reviewed at latest revision, 52 unresolved discussions.

Comments from Reviewable

LGTM, but leave the last word to Magi.
Previously, platosha (Anton Platonov) wrote…
> @magi42 please review this tutorial

Reviewed 1 of 1 files at r4.
Review status: all files reviewed at latest revision, 12 unresolved discussions.

Comments from Reviewable

An idea, could we add imports to an elements.html file included in the index.html. Then we add a note that you have to include the same file if you have tests in your project.
Previously, manolo (Manuel Carrasco Moñino) wrote…
> LGTM, but leave the last word to Magi.

Review status: 4 of 5 files reviewed at latest revision, 12 unresolved discussions.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 12 unresolved discussions.

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, platosha (Anton Platonov) wrote…
> I don’t think it is an issue. The reader not familiar with the Tour of Heroes doesn’t really miss any meaning of this paragraph.
>
> Linked the tour here as well, though.

True, I was not familiar with the heroes app, and I was able to follow all steps

Comments from Reviewable

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> True, I was not familiar with the heroes app, and I was able to follow all steps

That wasn't really my point.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 3 unresolved discussions.

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, tomivirkki (Tomi Virkki) wrote…
> That wasn't really my point.

So I misunderstood you.
Could be better if we say something like:
For this purpose we are going to create a staff management application similar to the one you can see in this example (and link with the live demo ) . But instead we will use the ready ...
Where we don't suppose that the user already knows the app, and he also can play with the app.
Also we could link to a live demo with the result of this app, so as the user understand what is the goal of using elements

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 3 unresolved discussions.

docs/tutorial.adoc, line 9 [r1] (raw file):
I don't think there is a problem. Now that I've linked the Tour of Heroes here, is the issue resolved, @tomivirkki?
If not, would it help if we drop the mention of the Tour completely in this paragraph? I mean, if we put it like this:

For this purpose we are going to create a staff management application. Instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.

@manolo the end result has a section below. We’d better put the live demo link there, I think.

Comments from Reviewable

Review status: 4 of 5 files reviewed at latest revision, 3 unresolved discussions.

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, platosha (Anton Platonov) wrote…
> I don't think there is a problem. Now that I've linked the Tour of Heroes here, is the issue resolved, @tomivirkki?
>
> If not, would it help if we drop the mention of the Tour completely in this paragraph? I mean, if we put it like this:
>
> > For this purpose we are going to create a staff management application. Instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.
>
> @manolo the end result has a section below. We’d better put the live demo link there, I think.

It could be my way, but normally when I'm going to follow a tutorial or quick start, very first I try the live demo. So I prefer it at the beginning.

Comments from Reviewable

docs/tutorial.adoc, line 9 [r1] (raw file):
Previously, manolo (Manuel Carrasco Moñino) wrote…
> It could be my way, but normally when I'm going to follow a tutorial or quick start, very first I try the live demo. So I prefer it at the beginning.

Yeah, the link resolves it for me at least.

Comments from Reviewable

The tutorial file is rather annoyingly long to review here. Perhaps it could be split up and use includes to compose it from multiple files. Just note that if you want to show it as a single page in the Docs site, you the included files should not have the header block or otherwise they will show as separate pages in the Docs site.
In a long tutorial like this, it would make sense to have a Table of Contents. It can be accomplished in two ways: 1) an AsciiDoc ToC in the page, as is done in the "Contributing" articles in the Docs site,  or 2) as a sub-menu, as is done in the Framework Tutorial.
Got only about half reviewed now. I'll call it a day and continue tomorrow.
Previously, manolo (Manuel Carrasco Moñino) wrote…
> An idea, could we add imports to an elements.html file included in the index.html. Then we add a note that you have to include the same file if you have tests in your project.

Reviewed 4 of 5 files at r1, 1 of 1 files at r5.
Review status: all files reviewed at latest revision, 33 unresolved discussions.

docs/tutorial.adoc, line 1 [r5] (raw file):

[[vaadin-angular2-polymer.tutorial]]

There's no header block in the beginning of the file, which is required by the Docs site.

docs/tutorial.adoc, line 13 [r5] (raw file):

This tutorial explains how to use Polymer elements in Angular 2 applications with the help of the [literal]`https://github.com/vaadin/angular2-polymer[@vaadin/angular2-polymer]` directives.

For this purpose we are going to create a staff management application similar to the https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] example. But unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.

Comma missing after introductory clause: "For this purpose, "
"are going to" -> "will"

docs/tutorial.adoc, line 17 [r5] (raw file):

=== The Start Point

This tutorial is based on the https://angular.io/docs/ts/latest/quickstart.html[Angular 2 5 min QuickStart] and the https://angular.io/docs/ts/latest/tutorial/[Angular 2 Tour of Heroes]. We are going to start from the empty application source from the https://angular.io/docs/ts/latest/quickstart.html[QuickStart repository].

"[Angular 2 5 min QuickStart]" -> "[5 Min QuickStart] for Angular 2"
Simply "We are going to start" -> "We start"
Looking at the page behind the link, the link doesn't link to a repository, but the "5 min QuickStart" page, and a "repository" mentioned anywhere in the page.
There shouldn't be two such link to the same page so nearby, and I have no idea what the repository means here.

docs/tutorial.adoc, line 19 [r5] (raw file):

This tutorial is based on the https://angular.io/docs/ts/latest/quickstart.html[Angular 2 5 min QuickStart] and the https://angular.io/docs/ts/latest/tutorial/[Angular 2 Tour of Heroes]. We are going to start from the empty application source from the https://angular.io/docs/ts/latest/quickstart.html[QuickStart repository].

If you are not yet familiar with Angular 2, please walk through the Angular 2 QuickStart and the Tour of Heroes first. In this tutorial we are going to skip the explanations that are already given in Angular 2 tutorials.

Move "first" from the end to "please first walk"
Missing comma after introductory clause: "In this tutorial, "

docs/tutorial.adoc, line 21 [r5] (raw file):

If you are not yet familiar with Angular 2, please walk through the Angular 2 QuickStart and the Tour of Heroes first. In this tutorial we are going to skip the explanations that are already given in Angular 2 tutorials.

=== The End Result

The title is a bit odd. Maybe rather: "A Look at the Goal" or something.

docs/tutorial.adoc, line 23 [r5] (raw file):

=== The End Result

In our heroes management application there will be two UI screens. This is the first screen with the list of all heroes made with Vaadin Grid of https://vaadin.com/elements[Vaadin Elements]:

Comma after introductory clause: "application, there"
"This is" – never refer to any screenshot (or almost anything else) with word "this". (It can only be used to refer something previously said, such as: "You eventually die. This is a common problem to people.") Always introduce illustrations and listings with word "following" or "shown". Here "The first screen, as illustrated in <<figure.vaadin-angular2-polymer.tutorial.result-heroes-list>>, uses Vaadin Grid to show a list of all the heroes..."

docs/tutorial.adoc, line 26 [r5] (raw file):

[[figure.vaadin-angular2-polymer.tutorial.result-heroes-list]]
.A Screenshot of the List of Heroes

Although it's sometimes useful to say that a screenshot is a screenshot, it's usually implicit. Maybe rather: "The first view with the list of heroes".
The new convention is to not capitalize figure titles, only section titles. (This applies to all image titles)

docs/tutorial.adoc, line 29 [r5] (raw file):

image::img/heroes-list-default.png[width="432",height="644"]

By clicking on a grid row, the user can open the the hero detail editor screen. It is made using Paper Input and Vaadin DatePicker:

double "the the"

docs/tutorial.adoc, line 40 [r5] (raw file):

== Creating Project

This tutorial is based on the Angular 2 QuickStart TypeScript source code. In this step, we create a new project on top of the QuickStart source code.

Is this the right moment to say on which this tutorial is based on. (What's TypeScript?)

I'd rephrase this somewhat as follows: "We begin by creating a new project based on the of the source code from the Angular 2 QuickStart project. You can either clone it from the GitHub repository or extract it from a ZIP package, as described next."

docs/tutorial.adoc, line 54 [r5] (raw file):

----
[prompt]#$# [command]#git# clone https://github.com/angular/quickstart my-project
[prompt]#$# [command]#cd# my-project

Use [replaceable]#my-project# style.

docs/tutorial.adoc, line 57 [r5] (raw file):

----

We are not going to contribute to the quickstart repository itself, so the original repository data is not needed. Remove the git repository data folder:

Deleting the repository info is a bit unnecessary. Even if not contributing, someone might want to have it locally, perhaps just to view diffs, and if not, it doesn't really disturb anyone.

docs/tutorial.adoc, line 66 [r5] (raw file):

=== Starting from the QuickStart ZIP Package

Alternatively, instead of using git to clone the QuickStart repository, you can download and extract the https://github.com/angular/quickstart/archive/master.zip[QuickStart zip package].

Git is a name and written capitalized: "Git"

docs/tutorial.adoc, line 70 [r5] (raw file):

=== Remove the AppComponent Tests

The QuickStart respository contains tests for [classname]#AppComponent#. Unfortunately, some changes to [classname]#AppComponent# in the following steps are going to break the compilation for these tests.

"in the following steps" - the steps don't follow immediately, so maybe rather: "that will be done in this tutorial"
"are going to" -> "would"
for -> of (?)

docs/tutorial.adoc, line 72 [r5] (raw file):

The QuickStart respository contains tests for [classname]#AppComponent#. Unfortunately, some changes to [classname]#AppComponent# in the following steps are going to break the compilation for these tests.

Please remove the [filename]#app/app.component.spec.ts# file to prevent its compilation errors introduced later in this tutorial.

The tutorial is going to introduce compilation errors? That sounds odd. If that is not the case, maybe just remove words "its" and "introduced".

docs/tutorial.adoc, line 82 [r5] (raw file):

====

=== Installing Npm Packages and Starting the Development Server

This is rather difficult case, as npm is a name written in lower case, so it should not be capitalized. Maybe use "npm" in lower case here (beginning of sentences is much more difficult case).

docs/tutorial.adoc, line 91 [r5] (raw file):

----

At this point you should be able to compile TypeScript source code and launch the development server. Let’s start the server to verify:

Comma after introductory clause: "At this point, "
Article: "compile the TypeScript source code" (source code is a category that requires the definite article and the name TypeScript is just a specifier)
Don't use contractions: "Let's" -> "Let us"

docs/tutorial.adoc, line 102 [r5] (raw file):

[TIP]
====
See the https://github.com/angular/quickstart/blob/master/README.md[QuickStart README] for more information about creating a new project and other useful [command]#npm# commands.

"QuickStart README" doesn't sound accurate enough here, rather say "Angular 2 QuickStart README" (the "Angular 2" could be before the link)

docs/tutorial.adoc, line 159 [r5] (raw file):

----

This file declares all Bower dependencies for our application. Now install them with this command:

"this" -> "the following"

docs/tutorial.adoc, line 166 [r5] (raw file):

----

After that, in your project root you should have the [filename]#bower_components# directory with all elements declared in the [filename]#bower.json#, together with the elements’ requirements. List the contents of the [filename]#bower_components# directory to verify that, it should contain these subdirectories:

Word order is a bit odd. Normally, a place (here "in your project root") should be after the object (here "directory"). You could have it in the beginning of the sentence as an introductory phrase, but there already is the time phrase. Hence maybe: "After that, you should have the ... directory in your project root, with all elements declared in the [filename]#bower.json# file".
(Note also the "bower.json" is a name, but the article requires a category. Hence add "file" to the end of the sentence" as above.)
"that, it should contain these" -> "that it contains the following"

docs/tutorial.adoc, line 168 [r5] (raw file):

After that, in your project root you should have the [filename]#bower_components# directory with all elements declared in the [filename]#bower.json#, together with the elements’ requirements. List the contents of the [filename]#bower_components# directory to verify that, it should contain these subdirectories:

.Contents of the bower_components Directory

You can use styles such as [filename]#bower_components# also in titles.

docs/tutorial.adoc, line 208 [r5] (raw file):

[TIP]
.Add bower_components to .gitignore

You can use styles such as [filename]#bower_components# also in titles.

docs/tutorial.adoc, line 210 [r5] (raw file):

.Add bower_components to .gitignore
====
It is ususally a good practice to exclude external dependencies from your source control. Angular 2 QuickStart source code already contains a [filename]#.gitignore# file, which excludes [filename]#node_modules# directory with npm dependencies from git repository of your application.

"ususally" -> "usually"
"Angular 2 QuickStart source code" -> "The source code of the Angular 2 QuickStart tutorial" (I'm not entirely sure about this but maybe better)
"file, which" -> "file that" (the latter clause is restrictive, because not all .gitignore files do exactly that exclusion)
Article missing: "excludes" -> "excludes the" (the ... directory)
Article missing: "from the Git repository"

docs/tutorial.adoc, line 222 [r5] (raw file):

=== Npm Dependency

Alongside with Bower dependencies, we also need to add one npm dependency to the project. `@vaadin/angular2-polymer` package adds support for Polymer elements in Angular 2 component templates. Run this command to install the package and save the dependency in [filename]#package.json# at the same time:

Article missing: "The `@vaadin/angular2-polymer` package"
This-syndrome: "Run this" -> "Run the following"

docs/tutorial.adoc, line 232 [r5] (raw file):

== Adding Polymer Elements to Our Application

In the previous step, we downloaded elements to bower_components directory. Now we are going to import these elements in our application.

Style and article: "the [filename]#bower_components# directory"
"in" -> "into" (not sure if necessary)

docs/tutorial.adoc, line 234 [r5] (raw file):

In the previous step, we downloaded elements to bower_components directory. Now we are going to import these elements in our application.

In your project root, edit the [filename]#index.html# file and replace the contents with these lines:

"these" -> "the following"

docs/tutorial.adoc, line 292 [r5] (raw file):

----

Here’s the list of important changes explained:

Don't use contractions
Rephrase as: "Some important changes needed to be done to the regular Angular 2 code. They are listed in the following:"

docs/img/app-layout.png, line 0 [r5] (raw file):
Screenshots should not normally have drop shadow and especially not transparency. This applies to anything going to a PDF, because the processor that we use to process DocBook uses black for backgrounds, not white. Hence, such screenshots will look horrible. As Elements documentation is currently not going to the print edition, this is not an immediate issue, but I'd nevertheless recommend using the practices. Also, the drop-shadows seem to create a rather huge margin, which may be an issue if space is limited, as it is in the print/PDF edition.
Another issue: many of these screenshots have a lot of empty space and are rather tall. Compactness is a virtue, especially in the print/PDF editions. Nevertheless, it's good that they have same height. Again, not currently absolutely urgent.

docs/img/hero-detail.png, line 0 [r5] (raw file):
Same transparency, shadow, and sizes issues as in other screenshots.

docs/img/heroes-list-default.png, line 0 [r5] (raw file):
Same transparency, shadow, and sizes issues as in other screenshots.

docs/img/heroes-list.png, line 0 [r5] (raw file):
Same transparency, shadow, and sizes issues as in other screenshots.

Comments from Reviewable

@magi42 I split the tutorial chapters to the separate files.
Added temporary auto-generated toc in the beginning, should help to navigate though the preview rendering. I would not like it to go out-of-sync with the tutorial text, if we change the structure during the review. Will replace with a proper submenu in the header block after this review.
Previously, magi42 (Marko Grönroos) wrote…
> The tutorial file is rather annoyingly long to review here. Perhaps it could be split up and use includes to compose it from multiple files. Just note that if you want to show it as a single page in the Docs site, you the included files should not have the header block or otherwise they will show as separate pages in the Docs site.
>
> In a long tutorial like this, it would make sense to have a Table of Contents. It can be accomplished in two ways: 1) an AsciiDoc ToC in the page, as is done in the "Contributing" articles in the Docs site,  or 2) as a sub-menu, as is done in the Framework Tutorial.
>
> Got only about half reviewed now. I'll call it a day and continue tomorrow.

Review status: 4 of 13 files reviewed at latest revision, 30 unresolved discussions.

docs/tutorial.adoc, line 1 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> There's no header block in the beginning of the file, which is required by the Docs site.

Right. It’s still uncertain at what place in the Docs site menu it will go. Will add the header block later.

docs/tutorial.adoc, line 13 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Comma missing after introductory clause: "For this purpose, "
> * "are going to" -> "will"

Done.

docs/tutorial.adoc, line 17 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "[Angular 2 5 min QuickStart]" -> "[5 Min QuickStart] for Angular 2"
> * Simply "We are going to start" -> "We start"
> * Looking at the page behind the link, the link doesn't link to a repository, but the "5 min QuickStart" page, and a "repository" mentioned anywhere in the page.
> * There shouldn't be two such link to the same page so nearby, and I have no idea what the repository means here.

Done.

docs/tutorial.adoc, line 19 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Move "first" from the end to "please first walk"
> * Missing comma after introductory clause: "In this tutorial, "

Done.

docs/tutorial.adoc, line 21 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> The title is a bit odd. Maybe rather: "A Look at the Goal" or something.

Changed to ”The Goal”.

docs/tutorial.adoc, line 23 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Comma after introductory clause: "application, there"
> * "This is" – never refer to any screenshot (or almost anything else) with word "this". (It can only be used to refer something previously said, such as: "You eventually die. This is a common problem to people.") Always introduce illustrations and listings with word "following" or "shown". Here "`The first screen, as illustrated in <>, uses Vaadin Grid to show a list of all the heroes...`"

Done.

docs/tutorial.adoc, line 26 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Although it's sometimes useful to say that a screenshot is a screenshot, it's usually implicit. Maybe rather: "The first view with the list of heroes".
> * The new convention is to not capitalize figure titles, only section titles. (This applies to all image titles)

Done.

docs/tutorial.adoc, line 29 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * double "the the"

Done.

docs/tutorial.adoc, line 40 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Is this the right moment to say on which this tutorial is based on. (What's TypeScript?)
>
> I'd rephrase this somewhat as follows: "We begin by creating a new project based on the of the source code from the Angular 2 QuickStart project. You can either clone it from the GitHub repository or extract it from a ZIP package, as described next."

Done.

docs/tutorial.adoc, line 54 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Use `[replaceable]#my-project#` style.

Done.

docs/tutorial.adoc, line 57 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Deleting the repository info is a bit unnecessary. Even if not contributing, someone might want to have it locally, perhaps just to view diffs, and if not, it doesn't really disturb anyone.

I removed the command, because it's not universal and applies to *nix systems only.
But I leaved the instruction to delete the Git repository data. If you want to view diffs, you can initialize a new repository right after that. The original repository history has no use here, but it's a waste of space.
As we teach developers how to create a new project here, we should also instruct them to remove the original history, to prevent them from keeping and distributing it by a mistake / because of lack of information.
Apart from these reasons, this step is listed in the QuickStart README.

docs/tutorial.adoc, line 66 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Git is a name and written capitalized: "Git"

Done.

docs/tutorial.adoc, line 70 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "in the following steps" - the steps don't follow immediately, so maybe rather: "that will be done in this tutorial"
> * "are going to" -> "would"
> * for -> of (?)

Done.

docs/tutorial.adoc, line 72 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * The tutorial is going to introduce compilation errors? That sounds odd. If that is not the case, maybe just remove words "its" and "introduced".

Done.

docs/tutorial.adoc, line 82 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * This is rather difficult case, as npm is a name written in lower case, so it should not be capitalized. Maybe use "npm" in lower case here (beginning of sentences is much more difficult case).

Done.

docs/tutorial.adoc, line 91 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Comma after introductory clause: "At this point, "
> * Article: "compile the TypeScript source code" (source code is a category that requires the definite article and the name TypeScript is just a specifier)
> * Don't use contractions: "Let's" -> "Let us"

Done.

docs/tutorial.adoc, line 102 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "QuickStart README" doesn't sound accurate enough here, rather say "Angular 2 QuickStart README" (the "Angular 2" could be before the link)

Done.

docs/tutorial.adoc, line 159 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> "this" -> "the following"

Done.

docs/tutorial.adoc, line 166 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Word order is a bit odd. Normally, a place (here "in your project root") should be after the object (here "directory"). You could have it in the beginning of the sentence as an introductory phrase, but there already is the time phrase. Hence maybe: "_After that, you should have the ... directory in your project root, with all elements declared in the [filename]#bower.json# file_".
> * (Note also the "bower.json" is a name, but the article requires a category. Hence add "file" to the end of the sentence" as above.)
> * "that, it should contain these" -> "_that it contains the following_"

Done.

docs/tutorial.adoc, line 168 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> You can use styles such as `[filename]#bower_components#` also in titles.

Feels wrong for me to use styles in the titles. I tried to avoid it. Are you sure that it looks good?
Some block titles are nothing else then a name of the following file. Should I also wrap them all in styles?

docs/tutorial.adoc, line 208 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> You can use styles such as `[filename]#bower_components#` also in titles.

Rephrased this title to not contain the file names.

docs/tutorial.adoc, line 210 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "ususally" -> "_usually_"
> * "Angular 2 QuickStart source code" -> "_The source code of the Angular 2 QuickStart tutorial_" (I'm not entirely sure about this but maybe better)
> * "file, which" -> "_file that_" (the latter clause is restrictive, because not all .gitignore files do exactly that exclusion)
> * Article missing: "excludes" -> "excludes _the_" (the ... directory)
> * Article missing: "from _the_ Git repository"

It's not the source code of the tutorial. It's the source code of the application that is the result of the QuickStart tutorial. Also, the “source code” is a bit inappropriate here, because the .gitignore file is not the actual code. Changed to: “The Angular 2 QuickStart project”.
Done.

docs/tutorial.adoc, line 222 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Article missing: "The \`@vaadin/angular2-polymer\` package"
> * This-syndrome: "Run this" -> "_Run the following_"

Done.

docs/tutorial.adoc, line 232 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Style and article: "_the [filename]#bower_components# directory_"
> * "in" -> "into" (not sure if necessary)
>

Done.

docs/tutorial.adoc, line 234 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "these" -> "the following"

Done.

docs/tutorial.adoc, line 292 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Don't use contractions
> * Rephrase as: "_Some important changes needed to be done to the regular Angular 2 code. They are listed in the following:_"

The rephrased sentence is not truth. The changes were already applied above. The changes were applied to the application index.html, not to the Angular 2 code. The changes are done by this sentence, we're just explaining, what have changed and why. Changed to: ```We applied some important changes in the [filename]#index.html# file. They are explained in the following list:```

Comments from Reviewable

Reviewed 8 of 9 files at r6, 1 of 1 files at r7.
Review status: all files reviewed at latest revision, 27 unresolved discussions.

Comments from Reviewable

Reviewed 4 of 5 files at r1.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

Comments from Reviewable

Reviewed 1 of 5 files at r1, 1 of 1 files at r5.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

Comments from Reviewable

Previously, platosha (Anton Platonov) wrote…
> @magi42 I split the tutorial chapters to the separate files.
>
> Added temporary auto-generated toc in the beginning, should help to navigate though the preview rendering. I would not like it to go out-of-sync with the tutorial text, if we change the structure during the review. Will replace with a proper submenu in the header block after this review.

Reviewed 2 of 9 files at r6.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

Comments from Reviewable

Reviewed 9 of 9 files at r8.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

Comments from Reviewable

The split-up looks good.
Previously, platosha (Anton Platonov) wrote…
> @magi42 I split the tutorial chapters to the separate files.
>
> Added temporary auto-generated toc in the beginning, should help to navigate though the preview rendering. I would not like it to go out-of-sync with the tutorial text, if we change the structure during the review. Will replace with a proper submenu in the header block after this review.

Reviewed 9 of 9 files at r6, 1 of 1 files at r7, 9 of 9 files at r8.
Review status: all files reviewed at latest revision, 91 unresolved discussions.

docs/tutorial.adoc, line 13 [r5] (raw file):
Previously, platosha (Anton Platonov) wrote…
> Done.

Oh, noticed something more: "we'll" -> "_we will_"

docs/tutorial.adoc, line 168 [r5] (raw file):
Previously, platosha (Anton Platonov) wrote…
> Feels wrong for me to use styles in the titles. I tried to avoid it. Are you sure that it looks good?
>
> Some block titles are nothing else then a name of the following file. Should I also wrap them all in styles?

Mmm, it's a difficult question, but I'd think it's better to always use the styles. I've also used them in book indexes and such.

docs/tutorial/creating-project.adoc, line 13 [r6] (raw file):

=== Starting from the QuickStart Repository

Clone the https://github.com/angular/quickstart[QuickStart repository] into the tutorial project folder:

Maybe it's good to be more exact here and say [Angular 2 QuickStart repository], so the reader doesn't think it's any Vaadin QuickStart repository.

docs/tutorial/creating-project.adoc, line 29 [r6] (raw file):

=== Remove the AppComponent Tests

The QuickStart respository contains tests for [classname]#AppComponent#. Unfortunately, some changes to [classname]#AppComponent#, that will be done in this tutorial, would break the compilation of these tests.

It's not clear to me what the "AppComponent" is (even with the style name). Maybe clarify "the [classname]#AppComponent# class".
There should not be comma before "that", as it is followed by a clause that restricts "some changes". Further, "to AppComponent" is a prepositional phrase starting with "to", which should come after the object of the clause. Hence rather: "Unfortunately, some changes that will be done to [classname]#AppComponent# in this tutorial would break the compilation of the tests."

docs/tutorial/creating-project.adoc, line 50 [r6] (raw file):

----

At this point, you should be able to compile the TypeScript source code and launch the development server. Let us start the server to verify:

Hmm, maybe rather use "You can start" after all, as that fits the style in other sentences here
Verify what? Verifying is a rather formal thing. Maybe rather: "start the server to check that everything is fine at this point:"

docs/tutorial/dependencies.adoc, line 30 [r6] (raw file):

  "main": "",
  "authors": [
    "Your Name"

You could use the [replaceable] style here for fillable values. You just need to use it very carefully, and possibly quite brackets with +++:
[source, json, subs="normal"]
.bower.json
----
{
  "name": "[replaceable]#my-project#",
  "description": "",
  "main": "",
  "authors": +++[+++
    "[replaceable]#Your Name#"+++]+++

docs/tutorial/dependencies.adoc, line 53 [r6] (raw file):

  }
}
----

Also here, using [replaceable] for version numbers and such would maybe clarify.

docs/tutorial/dependencies.adoc, line 55 [r6] (raw file):

----

The following file declares all Bower dependencies for our application. Now install them with this command:

There's no such file following this paragraph, so I don't know what file it refers to.
"this command" -> "the following command" (I hope there wasn't a confusion with my earlier correction to word "this" here)

docs/tutorial/dependencies.adoc, line 62 [r6] (raw file):

----

After that, you should have the [filename]#bower_components# directory in your project root, with all elements declared in the [filename]#bower.json# file, and their requirements. List the contents of the [filename]#bower_components# directory to verify that it contains the following subdirectories:

"have the" -> "have a" (the directory is mentioned for the first time and is not always the same)

docs/tutorial/dependencies.adoc, line 102 [r6] (raw file):

webcomponentsjs
----

Perhaps you could use a table or something to split the long list into 2-3 columns. Not necessary, but could do.

docs/tutorial/dependencies.adoc, line 106 [r6] (raw file):

.Ignore Bower Components in the Source Control
====
It is usually a good practice to exclude external dependencies from your source control. The Angular 2 QuickStart project already contains a [filename]#.gitignore# file that excludes the [filename]#node_modules# directory with npm dependencies from the Git repository of your application.

Source control with Git was earlier removed by removing the .git directoryfrom the QuickStart project. so this only has effect once it's again initialized for Git. Maybe rephrase this a bit.

docs/tutorial/dependencies.adoc, line 108 [r6] (raw file):

It is usually a good practice to exclude external dependencies from your source control. The Angular 2 QuickStart project already contains a [filename]#.gitignore# file that excludes the [filename]#node_modules# directory with npm dependencies from the Git repository of your application.

Please add the following line to the [filename]#.gitignore# file to also prevent Bower dependencies from being tracked by your source control:

Maybe rather "Please" -> "You can".
"also" looks a bit unnecessary there

docs/tutorial/dependencies.adoc, line 116 [r6] (raw file):

====

=== The Npm Dependency

Maybe again write npm in lower case here, as it's a name (and identifier) that starts with lower case.

docs/tutorial/hero-editor.adoc, line 4 [r6] (raw file):

== Hero Editor and Routing

Previously we added the heroes list in our application. In this step, we are going to add the editing feature. After that, the user should be able to navigate to the hero details by clicking a row in the heroes list, edit the details and get back to the list with the back button in the toolbar.

Use serial comma in the list: "details, and"

docs/tutorial/hero-editor.adoc, line 9 [r6] (raw file):

.Some Parts are Explained in the Tour of Heroes
====
This step partly follows the Angular 2 Tour of Heroes Tutorial. Therefore here we skip explaining the parts of the code that are similar in both this tutorial and the Tour of Heroes, like the routing requirements and configuration.

Add comma: "Therefore, "
"here" is an adverb that should usually go elsewhere... Can't decide how it should be so just let it be.
"in both" -> "both in"
"like" -> "such as"

docs/tutorial/hero-editor.adoc, line 11 [r6] (raw file):

This step partly follows the Angular 2 Tour of Heroes Tutorial. Therefore here we skip explaining the parts of the code that are similar in both this tutorial and the Tour of Heroes, like the routing requirements and configuration.

See https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] for the detailed explainations of the similar parts.

"explanations" ... or maybe it should be "for a detailed explanation of" (the tutorial itself is singular)

docs/tutorial/hero-editor.adoc, line 16 [r6] (raw file):

=== Add the Hero Get Method to the Service

Let us add the [methodname]#getHero(id: number)# method to the [classname]#HeroService#, that would be used to retrive a single hero in our application components. Open the [filename]#app/hero.service.ts# file and change its contents to the following code:

The getHero() method hasn't been mentioned or defined earlier, so the article probably should be indefinite (a).
No comma before "that", but then it comes ambiguous. Rather split the sentence: ". It can be used to retrieve"

docs/tutorial/hero-editor.adoc, line 42 [r6] (raw file):

=== Add the Hero Editor Component

Create the file [filename]#app/hero-detail.component.ts# and place these lines inside:

"the file" -> "a file with name"
"place these" -> "put the following"
"inside" -> "in it"

docs/tutorial/hero-editor.adoc, line 88 [r6] (raw file):

----

So, here we have just created [classname]#HeroDetailComponent#, the heroes editor for our application. It uses [elementname]#paper-input# bound to the [propertyname]#hero.name# and Vaadin DatePicker bound to the [propertyname]#hero.birthday# property this time with two-way data binding (i.e. with `[(value)]` syntax).

"Vaadin DatePicker" doesn't seem like the proper product name (camelcase DatePicker looks like a Java class name). Its docs page has title "Date Picker", but otherwise [vaadinelement]#vaadin-date-picker# seems to be used everywhere. Maybe use the element name here as well, like you do for the paper-input.
Comma missing: "property, this time" (assuming that it was done earlier with one-way or no data binding)
Don't use latin abbreviations: i.e. -> "(that is, with the" (notice the missing article).

docs/tutorial/hero-editor.adoc, line 90 [r6] (raw file):

So, here we have just created [classname]#HeroDetailComponent#, the heroes editor for our application. It uses [elementname]#paper-input# bound to the [propertyname]#hero.name# and Vaadin DatePicker bound to the [propertyname]#hero.birthday# property this time with two-way data binding (i.e. with `[(value)]` syntax).

[classname]#HeroDetailComponent# gets the hero [propertyname]#id# from [classname]#RouteParams# and calls [methodname]#getHero(id: number)# method from [classname]#HeroService# with the hero id argument to retrive the hero object. After the retrieval, the hero object is assigned to the [propertyname]#hero# property of [classname]#HeroDetailComponent#.

"hero id" – Write "ID" capitalized when you use it as abbreviation for "identifier" ("id" is more like some psychoanalysis stuff...), unless you are referring to a property or variable name, in which case the appropriate style should be used. I suppose you could use either way here.

docs/tutorial/hero-editor.adoc, line 92 [r6] (raw file):

[classname]#HeroDetailComponent# gets the hero [propertyname]#id# from [classname]#RouteParams# and calls [methodname]#getHero(id: number)# method from [classname]#HeroService# with the hero id argument to retrive the hero object. After the retrieval, the hero object is assigned to the [propertyname]#hero# property of [classname]#HeroDetailComponent#.

Since we use two-way binding, the [propertyname]#hero.name# and the [propertyname]#hero.birthday# subproperty values are automatically displayed in the corresponding elements, and when the user edits these values in the elements, the subproperties of [propertyname]#hero# property are updated automatically.

subproperty -> sub-property
subproperties -> sub-properties
Rather long sentence. You can split it at: "...elements. When the user..."

docs/tutorial/hero-editor.adoc, line 97 [r6] (raw file):

.Use ngIf When Loading Content
====
The hero object is retrived asynchronously after the component initialization. At this time when the retrieval starts, the component template is already rendered, but the [propertyname]#hero# i>s not loaded yet, so we can not use [propertyname]#hero.name# and [propertyname]#hero.birthday# subproperties. Using them at this moment would result in errors.

What's the i>sthere? Looks like typo.
sub-properties
"moment" sounds a bit too exact point in time -> time

docs/tutorial/hero-editor.adoc, line 99 [r6] (raw file):

The hero object is retrived asynchronously after the component initialization. At this time when the retrieval starts, the component template is already rendered, but the [propertyname]#hero# i>s not loaded yet, so we can not use [propertyname]#hero.name# and [propertyname]#hero.birthday# subproperties. Using them at this moment would result in errors.

That is why we wrap [elementname]#paper-input# and [elementname]#vaadin-date-picker# elements with `<div *ngIf="hero"></div>` in the component template. The `ngIf` structural directive not only hides the content, but also stops the hidden part of the template from being evaluated and rendered. This effectively prevents errors of accessing non-existant subproperties during the loading.

article: "wrap the"
sub-properties

docs/tutorial/hero-editor.adoc, line 102 [r6] (raw file):

====

Unlike with Vaadin Grid in the heroes list, we don’t want our editor contents to touch the edges of the browser window. It’s nice to have some spacing around them. For that reason we add `display: block;` and `padding: 16px;` rules in the styles section of our component metadata.

Don't use contractions such as don't. You could say "do not" or rephrase a bit, for example: "we want to avoid our editor contents from touching the edges"
Same with "it's"
Comma missing after introductory phrase: "For that reason, we"

docs/tutorial/hero-editor.adoc, line 106 [r6] (raw file):

=== Add Routing

The Angular 2 Component Router uses `history.pushState` API for navigation. This requires us to declare the base `href` for the main document. Add this line to the [filename]#index.html# file in the project root just after the `<head>` opening tag:

[elementname]#head#

docs/tutorial/hero-editor.adoc, line 114 [r6] (raw file):

----

Next, add routing, the back button and navigation reaction to the [classname]#AppComponent#. Edit [filename]#app/app.component.ts# to contain the code below:

Maybe rather: "Next, we add"
Serial comma missing: "back button, and navigation reaction"

docs/tutorial/hero-editor.adoc, line 208 [r6] (raw file):

----

Now we import [classname]#RouteConfig# decorator and some other Angular 2 Component Router parts. We also add [classname]#HeroDetailComponent# import alongside with [classname]#HeroesComponent#.

Article missing: "Now we import the" (the [identifier] decorator)
Article missing: "We also add the" (the [identifier] import)

docs/tutorial/hero-editor.adoc, line 210 [r6] (raw file):

Now we import [classname]#RouteConfig# decorator and some other Angular 2 Component Router parts. We also add [classname]#HeroDetailComponent# import alongside with [classname]#HeroesComponent#.

As usual with the routing in Angular 2, we add [classname]#ROUTER_DIRECTIVES# to the [propertyname]#directives# array of [classname]#AppComponent# component metadata, as well as [classname]#ROUTER_PROVIDERS# to the [propertyname]#providers# array.

Probably extra article -> "with routing".

docs/tutorial/hero-editor.adoc, line 212 [r6] (raw file):

As usual with the routing in Angular 2, we add [classname]#ROUTER_DIRECTIVES# to the [propertyname]#directives# array of [classname]#AppComponent# component metadata, as well as [classname]#ROUTER_PROVIDERS# to the [propertyname]#providers# array.

We use [classname]#RouteConfig# decorator to declare routes in our application. There are two routes, one for the heroes list ([classname]#HeroesComponent#), and another for the hero detail editor ([classname]#HeroDetailComponent#).

"We use the" (the...decorator)
Use colon rather than comma to introduce a list
There should be no comma before "and"

docs/tutorial/hero-editor.adoc, line 214 [r6] (raw file):

We use [classname]#RouteConfig# decorator to declare routes in our application. There are two routes, one for the heroes list ([classname]#HeroesComponent#), and another for the hero detail editor ([classname]#HeroDetailComponent#).

Note that the first route has `useAsDefault: true;` option in order to open the heroes list by default.

"route has the" (the...option)

docs/tutorial/hero-editor.adoc, line 220 [r6] (raw file):

=== Navigation from List to Detail

The last feature to implement in this step is navigation from the heroes list to the hero detail by clicking a row. Open [filename]#app/heroes.component.ts# and change it to contain the following code:

plural missing? "hero details"?
The sentence is a bit complex, but maybe not too much.

docs/tutorial/hero-editor.adoc, line 283 [r6] (raw file):

----

Now when the user clicks a row inside the heroes list, [elementname]#vaadin-grid# fires [eventname]#selected-items-changed# event. We bound the event to the [methodname]#onSelectedItemsChanged(event: any)# method of the [classname]#HeroesComponent#. In listener method, we read the selected item index, get the [propertyname]#id# property of the corresponding [propertyname]#heroes# array item and call [methodname]#goToHeroDetailById(id: number)#, which uses [classname]#Router# to navigate to the hero detail of the selected hero.

Article missing: "In the listener method"
Serial comma missing: "item, and"

docs/tutorial/hero-editor.adoc, line 289 [r6] (raw file):

All the changes for this step are done. Now launch your application again and try how the navigation works.

After opening the application, click the first row in the heroes list. You should see the detail view like in the following screenshot:

"detail view" – I think in master-detail views, the detail are usually plural (there's more that one) and the views named in plural form. Hence, I'd rather use "details view" (also elsewhere in the tutorial). Also the Angular 2 tutorial seems to use that, but is not very consistent about it. In some cases it's OK to use singular, such as "hero detail data" .

docs/tutorial/hero-editor.adoc, line 292 [r6] (raw file):

[[figure.vaadin-angular2-polymer.tutorial.hero-detail]]
.A Screenshot of Hero Detail View

You don't usually need to say that an image is a screenshot or such. (Think of a picture in a newspaper with title starting "Picture of ...")
Article missing, and figure titles should no longer be capitalized: "The hero detail view"

docs/tutorial/hero-editor.adoc, line 299 [r6] (raw file):

=== Nice Touches in the AppComponent

Here are the UX-related changes to AppComponent explained.

"Here" is a bit improper reference to the section itself. Maybe rather: "In the following, we go through and explain all the UX-related changes that were made to the AppComponent class earlier."
AppComponent is a class, so use [classname] like elsewhere

docs/tutorial/hero-editor.adoc, line 303 [r6] (raw file):

==== Dynamic Toolbar Title

We add the [propertyname]#title# property to the [classname]#AppComponent# and bind it to the text content of `<div title spacer></div>` inside the toolbar in the template.

The "Nice Touches" section appears to be about changes that we did earlier, so it's more proper to use past rather than present tense.

"We added...", "bound", etc. This applies to many verbs in the entire "Nice Touches" section (though not all).

docs/tutorial/hero-editor.adoc, line 305 [r6] (raw file):

We add the [propertyname]#title# property to the [classname]#AppComponent# and bind it to the text content of `<div title spacer></div>` inside the toolbar in the template.

Instead of a static title, the title is now updated dynamically. We subscribe to the [classname]#Router# in [classname]#AppComponent# and use [classname]#RouteData# in the navigation event callback to get the title value specified for the current route. Each time after user opens the application or navigates inside, the [classname]#Router# event is dispatched so the [propertyname]#title# property is updated.

Maybe rather: "dispatched so that".
Maybe "will be updated"  should be used, as it will happen after the event is dispatched.

docs/tutorial/hero-editor.adoc, line 309 [r6] (raw file):

==== The Back Icon in the Toolbar

We add [elementname]#paper-icon-button# to have a back icon inside the [elementname]#app-toolbar# in the template. The icon has a click event binding, which calls [methodname]#goBack()# method of [classname]#AppComponent#. In the method, we invoke [methodname]#navigate(linkParams: any[])# method of the [classname]#Router# to navigate back to the heroes list from the hero detail.

...use the past tense here as well... added
Article: "calls the ... method"
Article: "invoke the ... method"
"hero details" again here. The plural really fits here (and most other cases) much better than singular.

docs/tutorial/hero-editor.adoc, line 311 [r6] (raw file):

We add [elementname]#paper-icon-button# to have a back icon inside the [elementname]#app-toolbar# in the template. The icon has a click event binding, which calls [methodname]#goBack()# method of [classname]#AppComponent#. In the method, we invoke [methodname]#navigate(linkParams: any[])# method of the [classname]#Router# to navigate back to the heroes list from the hero detail.

When the heroes list is shown, the back icon is useless, so we need to hide it. To achieve that, we added [propertyname]#isInChildView# property to [classname]#AppComponent#, which is updated from the route data in the navigation event callback. In the template we add `*ngIf="isInChildView"` for the [elementname]#paper-icon-button#.

(No need for past tense in the first sentence)  .... (later) added

docs/tutorial/hero-editor.adoc, line 317 [r6] (raw file):

==== Dynamic Toolbar Shadow

To make the toolbar look better, we make the application toolbar to have a shadow that is shown only for the hero detail view, but not for the heroes list view. For this purpose we bind the `raised` class of the [elementname]#app-toolbar# to [propertyname]#isInChildView# property and add a style rule which applies the shadow mixin from [elementname]#paper-styles# to the [elementname]#app-toolbar# when it has the `raised` class.

Made, bound, added
Comma after introductory phrase: "For this purpose, we bound"

docs/tutorial/introduction.adoc, line 8 [r6] (raw file):

This tutorial explains how to use Polymer elements in Angular 2 applications with the help of the [literal]`https://github.com/vaadin/angular2-polymer[@vaadin/angular2-polymer]` directives.

For this purpose, we will to create a staff management application similar to the https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] example. But unlike in the Angular 2 Tour of Heroes, instead of implementing the UI elements in place, we’ll use the ready-made UI elements that are built on top of the Web Components technology stack. The resulting application will have a nice-looking mobile-first Material designed UI.

"we will to" -> "we show how to" (maybe not necessary to use future here)
"we'll" -> "we will"

docs/tutorial/introduction.adoc, line 14 [r6] (raw file):

This tutorial is based on the https://angular.io/docs/ts/latest/quickstart.html[5 min QuickStart] for Angular 2 and the https://angular.io/docs/ts/latest/tutorial/[Angular 2 Tour of Heroes]. We start from the QuickStart application source.

If you are not yet familiar with Angular 2, please first walk through the Angular 2 QuickStart and the Tour of Heroes. In this tutorial, we are going to skip the explanations that are already given in Angular 2 tutorials.

"please" -> "we advice you to"
"we are going to skip" -> "we skip"
Article missing: "given in the"

docs/tutorial/introduction.adoc, line 24 [r6] (raw file):

image::img/heroes-list-default.png[width="432",height="644"]

By clicking on a grid row, the user can open the hero detail editor screen. It is made using Paper Input and Vaadin DatePicker:

Is "Paper Input" a valid product name? At least paper-input documentation only seems to talk about the paper-input element (use [elementname]).
Same for Vaadin Date Picker (which is used once in the documentation title, but otherwise [vaadinelement]#vaadin-date-picker# is used.
Note again the "hero detail" vs "details" in this file

docs/tutorial/layout.adoc, line 4 [r6] (raw file):

== Building the Application Layout with Paper Elements

After the previous step we have some Polymer elements imported in [filename]#index.html# of our application. In this step, we are going to use them to create an application layout with a toolbar in [classname]#AppComponent#.

Comma missing after introductory phrase: "step, we"
Article: name "index.html " is really used like a common noun rather than a name here, so maybe it's better to put the noun there: "in the [filename]#index.html# file"

docs/tutorial/layout.adoc, line 8 [r6] (raw file):

=== Updating SystemJS Configuration

For using Polymer elements in our Angular components we need to import [classname]#PolymerElement# directives from `@vaadin/angular2-polymer`. Thus we need to make the module loader (SystemJS, in our case) aware of how to load the `@vaadin/angular2-polymer` package.

Comma after introductory clause: "components, we"
Article: "import the"
"Thus" -> "Therefore, "

docs/tutorial/layout.adoc, line 10 [r6] (raw file):

For using Polymer elements in our Angular components we need to import [classname]#PolymerElement# directives from `@vaadin/angular2-polymer`. Thus we need to make the module loader (SystemJS, in our case) aware of how to load the `@vaadin/angular2-polymer` package.

Angular 2 TypeScript QuickStart contains SystemJS packages import configuration in the [filename]#systemjs.config.js# file in the project root. Please edit this file and add mapping for the `@vaadin` scope and the `@vaadin/angular2-polymer` package there like follows:

Move the prepositional phrase after the object: "contains import configuration for the SystemJS packages" (notice the article)
mapping -> mappings
like -> as

docs/tutorial/layout.adoc, line 103 [r6] (raw file):

----

Save changes and launch the development server to see the results in your browser. After loading, your application should have this look:

Save the changes
...should look as follows:

docs/tutorial/layout.adoc, line 106 [r6] (raw file):

[[figure.vaadin-angular2-polymer.tutorial.app-layout]]
.A Screenshot of Empty Application Layout

No need to say "screenshot of"
Image titles should not be capitalized (any longer)

docs/tutorial/layout.adoc, line 109 [r6] (raw file):

image::img/app-layout.png[width="432",height="644"]

Now your application has a layout made by using [elementname]#app-header-layout#, [elementname]#app-header# and [elementname]#app-toolbar#.

Article and category: "using the ..... elements" (at the end of the sentence)
Serial comma: ", and"

docs/tutorial/layout.adoc, line 113 [r6] (raw file):

=== Elements Used in This Step

[elementname]#app-header-layout#:: The application layout consisting of the [elementname]#app-header# and the main contents. In our case, it adds a scrollable container for the application contents as well.

maybe rather "consisting" -> "that consists"
"element and the"

docs/tutorial/layout.adoc, line 122 [r6] (raw file):

.app-layout Elements are Design-Agnostic
====
Polymer elements from [elementname]#app-layout# set, including [elementname]#app-toolbar# that we use, are design-agnostic. They do not have Material Design look by default. We need to adjust [elementname]#app-toolbar# styles a bit.

article: "from the" (...set)

docs/tutorial/layout.adoc, line 124 [r6] (raw file):

Polymer elements from [elementname]#app-layout# set, including [elementname]#app-toolbar# that we use, are design-agnostic. They do not have Material Design look by default. We need to adjust [elementname]#app-toolbar# styles a bit.

Therefore we added color rules for the [elementname]#app-toolbar# in the styles of the [classname]#AppComponent#. Here we reuse the color values of default theme from [elementname]#paper-styles#.

Comma: "Therefore, "
Remove "here" and simply say "We reuse"

docs/tutorial/layout.adoc, line 126 [r6] (raw file):

Therefore we added color rules for the [elementname]#app-toolbar# in the styles of the [classname]#AppComponent#. Here we reuse the color values of default theme from [elementname]#paper-styles#.

Apart from the colors, it inherits the font family declared for the body. We have already decleared our font settings for the body in [filename]#index.html# earliear during this step.

decleared -> declared
earliear -> earlier
Use "the ... file" for the index.htmk

docs/tutorial/layout.adoc, line 132 [r6] (raw file):

.PolymerElement Directives
====
In order to enable all features of Polymer elements used inside your Angular component templates, remember to import [classname]#PolymerElement# in the component file and add `PolymerElement('element-name')` line for each Polymer element you use to the [propertyname]#directives# array of your component metadata.

"In order to use Polymer elements in your Angular component templates" (assuming that they or their features are not enabled even partially if there's no such import statement)
"each Polymer element that you use"

docs/tutorial/list-heroes.adoc, line 4 [r6] (raw file):

== List Heroes with Vaadin Grid

In the previous step we added the application layout with [elementname]#app-layout# elements. Next we are going add actual application content. Our plan is to use Vaadin Grid to list Heroes.

CAIP: "step, we"
"Next, we"

docs/tutorial/list-heroes.adoc, line 9 [r6] (raw file):

.Some Parts are Explained in the Tour of Heroes
====
This step partly follows the Angular 2 Tour of Heroes Tutorial. Therefore here we skip explaining the parts of the code that are similar in both this tutorial and the Tour of Heroes, like the [classname]#Hero# class and the [classname]#HeroService#.

"Therefore, "
Just remove "here"... I don't think it can be there before the subject of the sentence in this case.
like -> such as

docs/tutorial/list-heroes.adoc, line 11 [r6] (raw file):

This step partly follows the Angular 2 Tour of Heroes Tutorial. Therefore here we skip explaining the parts of the code that are similar in both this tutorial and the Tour of Heroes, like the [classname]#Hero# class and the [classname]#HeroService#.

See https://angular.io/docs/ts/latest/tutorial/[Tour of Heroes] for the detailed explainations of these parts.

"these" -> "such similar"

docs/tutorial/list-heroes.adoc, line 16 [r6] (raw file):

=== Hero Class

Let us start with creating the [classname]#Hero# class. Add [filename]#app/hero.ts# file with the following contents:

with -> by
"Add" -> "Create a"

docs/tutorial/list-heroes.adoc, line 28 [r6] (raw file):

----

Unlike in Angular 2 Tour of Heroes, in our application we are about to store and expose birthday of each hero for the user. Here we add `birthday: string;` property to our [classname]#Hero# class.

"we are about to store" sounds really odd here. Maybe rather just "we store"
article: "the birthday"

docs/tutorial/list-heroes.adoc, line 35 [r6] (raw file):

Why are we using the [classname]#string# type and not [classname]#Date# to store dates? There are two reasons:

. Builtin JavaScript [classname]#Date# type is always stored as a timestamp, so it always contains the exact time information. This is not only redundant, but also harder to use than a plain string in case of storing just a date. It requires extra care about the correct time and timezone when storing the value and displaying it to the user, otherwise we might get incorrect dates because of timezone mismatches.

builtin -> built-in
Article: "The built-in"
Use semicolon and comma: "to the user; otherwise, we might"

docs/tutorial/list-heroes.adoc, line 37 [r6] (raw file):

. Builtin JavaScript [classname]#Date# type is always stored as a timestamp, so it always contains the exact time information. This is not only redundant, but also harder to use than a plain string in case of storing just a date. It requires extra care about the correct time and timezone when storing the value and displaying it to the user, otherwise we might get incorrect dates because of timezone mismatches.

. `Vaadin DatePicker`, as well as native HTML5 `<input type="date">`, gives the date value as an ISO-formatted [classname]#string#. To keep the simplicity, in our application we also store dates as strings, avoiding conversions.

There no a "Vaadin DatePicker" product or class, just talk about "The [vaadinelement]#vaadin-date-picker# element"
The introductory prepositional phrases should be grouped before the comma: "To preserve the simplicity in our application, we also store..." (preserve is maybe better than keep)

docs/tutorial/list-heroes.adoc, line 42 [r6] (raw file):

=== Mock Heroes Data

Add [filename]#app/mock-heroes.ts# file with some heroes data:

Add -> Create a

docs/tutorial/list-heroes.adoc, line 65 [r6] (raw file):

=== The Hero Service

We also need a [classname]#HeroService# to be able to retrive the heroes list in our Angular application. Add [filename]#app/hero.service.ts# file:

"Add" -> "Create a"

docs/tutorial/list-heroes.adoc, line 133 [r6] (raw file):

----

Here in [classname]#HeroesComponent# we have the [elementname]#vaadin-grid# element in the template. In styles, there is a `height: 100%;` rule for [elementname]#vaadin-grid#. In the template, inside [elementname]#vaadin-grid# there are three columns specified with their corresponding item property names.

Comma after introductory phrase: ", we have"
Articles and category: "In the styles, we have a ... rule for the ... element."
The prepositional phrase "inside vaadin-grid" should be somewhere else. Maybe after the object and separate the rest as a dependent clause: "In the template, there are three columns inside the [vaadinelement]#vaadin-grid# element, specified by their..."

docs/tutorial/list-heroes.adoc, line 135 [r6] (raw file):

Here in [classname]#HeroesComponent# we have the [elementname]#vaadin-grid# element in the template. In styles, there is a `height: 100%;` rule for [elementname]#vaadin-grid#. In the template, inside [elementname]#vaadin-grid# there are three columns specified with their corresponding item property names.

Also in the template, the [propertyname]#items# property of [elementname]#vaadin-grid# is bound to the [propertyname]#heroes# array property of [classname]#HeroesComponent#. At the same time, we import and use [classname]#HeroService# to get the list of heroes and assign the [propertyname]#heroes# property. Angular component data binding takes care of updating [propertyname]#items# property of [elementname]#vaadin-grid# with the list of heroes for us.

Maybe rather: "Data binding of Angular components takes..."
Article: "updating the"

docs/tutorial/list-heroes.adoc, line 145 [r6] (raw file):

=== Displaying Heroes List

Finally in this step, change [filename]#app/app.component.ts# to provide [classname]#HeroService# for our application and display the heroes list component:

change -> "you need to edit the ... file" ("we edit" or change would sound a bit odd, as it's clearly a task for the reader, not something we describe)

docs/tutorial/list-heroes.adoc, line 187 [r6] (raw file):

----

Here is what have changed in [filename]#app/app.component.ts#:

Rather: "We did the following changes in the ... file:"

docs/tutorial/list-heroes.adoc, line 189 [r6] (raw file):

Here is what have changed in [filename]#app/app.component.ts#:

* We import [classname]#HeroService# and list it in [propertyname]#providers#

"We imported ... and listed it..."

docs/tutorial/list-heroes.adoc, line 190 [r6] (raw file):

* We import [classname]#HeroService# and list it in [propertyname]#providers#
* We also import [classname]#HeroesComponent#, append it to [propertyname]#directives# and replace `<div>My application content</div>` to `<my-heroes></my-heroes>`

"We also imported ... and appended it to ... and replaced ..."

docs/tutorial/list-heroes.adoc, line 192 [r6] (raw file):

* We also import [classname]#HeroesComponent#, append it to [propertyname]#directives# and replace `<div>My application content</div>` to `<my-heroes></my-heroes>`

Now it’s time to look at the browser window again to the heroes list in our application. Here is how it should look like:

"Now it is again time to take a look in the browser window, to see how the heroes list looks in our application. It should look about as in <<figure.vaadin-angular2-polymer.tutorial.heroes-list>>."

docs/tutorial/list-heroes.adoc, line 195 [r6] (raw file):

[[figure.vaadin-angular2-polymer.tutorial.heroes-list]]
.A Screenshot of the Application with the List of Heroes

Simply: "The application with the list of heroes"

docs/tutorial/list-heroes.adoc, line 196 [r6] (raw file):

[[figure.vaadin-angular2-polymer.tutorial.heroes-list]]
.A Screenshot of the Application with the List of Heroes
image::img/heroes-list.png[width="432",height="644"]

I'm not entirely sure if specifying the width and height are recommended. They are primarily scaling parameters and could cause trouble if the width is wider than the text column width. Probably no problem in this tutorial, as the width is smaller than the column width and may help with rendering. (Also, you need to change the sizes if you take the screenshots again.)

docs/tutorial/polymer.adoc, line 4 [r6] (raw file):

== Adding Polymer Elements to Our Application

In the previous step, we downloaded elements to the [filename]#bower_components# directory. Now we are going to import these elements in our application.

Maybe: "downloaded the needed elements" (or rather "web components"?)
"Now we are going to" -> "Next, we will"

docs/tutorial/polymer.adoc, line 64 [r6] (raw file):

----

Here is the list of important changes explained:

We have made the following important changes to the original Angular 2 tutorial file:

docs/tutorial/polymer.adoc, line 67 [r6] (raw file):

The Doctype Declaration::
We added the `<!DOCTYPE html>` declaration in the first line of the HTML file. It switches document to use Standards mode, as required by the internals of [vaadinelement]#vaadin-grid#.

"to use the Standards mode"

docs/tutorial/polymer.adoc, line 70 [r6] (raw file):

The Web Components Polyfill::
The technology stack behind Web Components (namely, HTML Imports, Shadow DOM and Custom Elements) is not yet natively supported in all browses. Therefore we added the [filename]#webcomponents-lite.min.js# polyfill.

Serial comma missing ", and". (It's also rather complex sentence but maybe just let it be.)
browses -> browsers
"Therefore, we"

docs/tutorial/polymer.adoc, line 76 [r6] (raw file):

SystemJS App Import Change::
In some browsers, HTML Imports are loaded asynchronously. But we need them to be completely loaded before we import our Angular application. Hence we wrapped `System.import('app')...` call in the listener callback of the [eventname]#WebComponentsReady# event, which is fired by the polyfill after all imports are loaded and elements have been registered.

Too informal to begin sentence with "But" here, rather separate it with comma.  Maybe rather: "...asynchronously, but we need to have them completely..."
Article: "we wrapped the"

docs/tutorial/polymer.adoc, line 81 [r6] (raw file):

.Load Order
====
The order of loading Polymer elements and the rest of the Angular application code does matter. It is required to have Polymer elements loaded and registered before importing the Angular application. `@vaadin/angular2-polymer` package strictly depends on that.

Sounds a bit ambiguous: "The order of [loading Polymer elements]" -> "The order in which the Polymer elements and the rest of the Angular application code are loaded does matter"
Maybe rather: "required that Polymer elements are loaded"
Article: "The ... package..."

docs/tutorial/polymer.adoc, line 85 [r6] (raw file):

Style Changes::
Polymer elements come with nice builtin styles in the way of Material Design. Angular 2 also provides style encapsulation mechanisms for our application components.

builtin -> built-in

docs/tutorial/polymer.adoc, line 87 [r6] (raw file):

Polymer elements come with nice builtin styles in the way of Material Design. Angular 2 also provides style encapsulation mechanisms for our application components.
+
So the global styles are not needed anymore. Therefore we removed the [filename]#styles.css# external stylesheet and replaced it with [elementname]#iron-flex-layout# and [elementname]#paper-styles# style mixins imports and one embedded global style rule for body.

"So" -> "Therefore, "
We now how to change the other "Therefore": "For this purpose, we removed ..."
word order: "the external [filename]#styles.css# stylesheet"
remove double plural: "style mixin imports"
"one" -> "an" (unless there were previously multiple and now just one)
"...rule for the body element." (?)

docs/tutorial/polymer.adoc, line 89 [r6] (raw file):

So the global styles are not needed anymore. Therefore we removed the [filename]#styles.css# external stylesheet and replaced it with [elementname]#iron-flex-layout# and [elementname]#paper-styles# style mixins imports and one embedded global style rule for body.
+
The body style is the only global style that remains in our application. The body styles are needed to occupy the full height of the browser viewport, and also to specify default font styles, line height, background, and text colors.

"The body styles" – wasn't there just one style? I assume you mean the content of the style, so maybe rather: "The body element needs to be styled to take the full height..." (maybe use "take" rather than "occupy")

docs/tutorial/polymer.adoc, line 93 [r6] (raw file):

[TIP]
====
Instead of figuring out the exact rules and values for the body style, here we import and reuse CSS mixins and CSS custom properties declared in [elementname]#iron-flex-layout# and [elementname]#paper-styles#.

"here we" sounds improper after introductory clause. Maybe just leave "here" out.

docs/tutorial/polymer.adoc, line 98 [r6] (raw file):

[IMPORTANT]
====
When using custom CSS mixins and custom CSS properties in your main document styles, wrap your styles inside a `<style is="custom-style"></style>` tag.

"wrap" -> "you need to wrap"

docs/tutorial/polymer.adoc, line 106 [r6] (raw file):

[NOTE]
.Duplicated Imports Handling

Rather "Handling Duplicated mports"

docs/tutorial/polymer.adoc, line 108 [r6] (raw file):

.Duplicated Imports Handling
====
Our HTML imports also import their dependencies. As In the resulting dependency tree there might be multiple imports of the the same file. In this case, the duplicated fetch of the same file is prevented in browsers by checking the file location.

First sentence is very unclear. Does it mean: "The import statements in our HTML file also import any possible dependencies."
Some more problems. Rephrase the rest: "Imports having the same dependencies may result in multiple imports of the same file. In such case, browsers prevent fetching the same file multiple times by checking the file location."

docs/tutorial/wrap-up.adoc, line 4 [r6] (raw file):

== Wrap Up

All the tutorial steps are complete. Now you can use all powers of Polymer elements in your Angular 2 applications and know how to do it.

"You have now finished all the steps in the tutorial and know how to use all the powers of Polymer elements in your Angular 2 applications."

docs/tutorial/wrap-up.adoc, line 8 [r6] (raw file):

TODO: Link the resulting application code repository in this section when it gets published.

=== Next Steps

"Further Steps"

docs/tutorial/wrap-up.adoc, line 10 [r6] (raw file):

=== Next Steps

There are several ways of improvement for our application. For example, you might want to add an explicit “Save” button to the hero detail editor and make the user able to intentionally submit or discard their changes. To do that, use the `ngForm` directive. See the https://angular.io/docs/ts/latest/guide/forms.html[Forms Chapter] in the Angular 2 Basics guide for the detailed instructions.

"There are several ways to improve the application you created in this tutorial."
"explicit [guibutton]#Save# button"
"use" -> "you can use"

docs/tutorial/wrap-up.adoc, line 12 [r6] (raw file):

There are several ways of improvement for our application. For example, you might want to add an explicit “Save” button to the hero detail editor and make the user able to intentionally submit or discard their changes. To do that, use the `ngForm` directive. See the https://angular.io/docs/ts/latest/guide/forms.html[Forms Chapter] in the Angular 2 Basics guide for the detailed instructions.

In the tutorial, we did not consider the topic of storing your application data. For simplicity, our application uses mock in-memory data and relies on data binding to make temporary changes, that are not saved anywhere. You might want to move the heroes data to a server and add some HTTP API calls in your application. See the Angular 2 https://angular.io/docs/ts/latest/guide/server-communication.html[Http Client] documentation to know how to do that.

"that are" -> "which are" (it doesn't seem to be a restrictive clause and there shouldn't be comma before "that" anyhow, but it should be used with which)

docs/tutorial/wrap-up.adoc, line 16 [r6] (raw file):

Read the https://www.polymer-project.org/1.0/[Polymer Project] website to know about other features that Polymer provides you with. There is also the https://www.polymer-project.org/1.0/start/[Getting Started] guide, where you can learn how to create your own elements and apps based on Polymer.

Don’t forget to find out other elements you can use for building your applications on the https://vaadin.com/elements[Vaadin Elements] page and in the https://elements.polymer-project.org/[Polymer Catalog].

"Don't" – ...well, the informal style sort of fits here really well, sooo.... :-(
"... find out about other elements that you ..."
Maybe it should be "from the ... page" rather than "on the ... page". Can then also omit "in" later.

Comments from Reviewable

The images still seem to have drop shadows. Not sure if my comments on them were visible, so here it goes again:
Screenshots should not normally have drop shadow and especially not transparency. This applies to anything going to a PDF, because the processor that we use to process DocBook uses black for backgrounds, not white. Hence, such screenshots will look horrible. As Elements documentation is currently not going to the print edition, this is not an immediate issue, but I'd nevertheless recommend using the practices. Also, the drop-shadows seem to create a rather huge margin, which may be an issue if space is limited, as it is in the print/PDF edition.
Another issue: many of these screenshots have a lot of empty space and are rather tall. Compactness is a virtue, especially in the print/PDF editions. Nevertheless, it's good that they have same height. Again, not currently absolutely urgent.
Previously, magi42 (Marko Grönroos) wrote…
> The split-up looks good.

Review status: all files reviewed at latest revision, 89 unresolved discussions.

Comments from Reviewable

@magi42 will crop the images tomorrow.
Previously, magi42 (Marko Grönroos) wrote…
> The images still seem to have drop shadows. Not sure if my comments on them were visible, so here it goes again:
>
> Screenshots should not normally have drop shadow and especially not transparency. This applies to anything going to a PDF, because the processor that we use to process DocBook uses black for backgrounds, not white. Hence, such screenshots will look horrible. As Elements documentation is currently not going to the print edition, this is not an immediate issue, but I'd nevertheless recommend using the practices. Also, the drop-shadows seem to create a rather huge margin, which may be an issue if space is limited, as it is in the print/PDF edition.
>
> Another issue: many of these screenshots have a lot of empty space and are rather tall. Compactness is a virtue, especially in the print/PDF editions. Nevertheless, it's good that they have same height. Again, not currently absolutely urgent.
>

Review status: 5 of 14 files reviewed at latest revision, 89 unresolved discussions.

docs/tutorial.adoc, line 13 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Oh, noticed something more: "we'll" -> "_we will_"

Done.

docs/tutorial.adoc, line 168 [r5] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Mmm, it's a difficult question, but I'd think it's better to always use the styles. I've also used them in book indexes and such.

Done.

docs/tutorial/creating-project.adoc, line 13 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Maybe it's good to be more exact here and say [Angular 2 QuickStart repository], so the reader doesn't think it's any Vaadin QuickStart repository.

Done.

docs/tutorial/creating-project.adoc, line 29 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * It's not clear to me what the "AppComponent" is (even with the style name). Maybe clarify "the [classname]#AppComponent# class".
> * There should not be comma before "that", as it is followed by a clause that restricts "some changes". Further, "to AppComponent" is a prepositional phrase starting with "to", which should come after the object of the clause. Hence rather: "_Unfortunately, some changes that will be done to [classname]#AppComponent# in this tutorial would break the compilation of the tests._"
>

Done.

docs/tutorial/creating-project.adoc, line 50 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Hmm, maybe rather use "You can start" after all, as that fits the style in other sentences here
> * Verify what? Verifying is a rather formal thing. Maybe rather: "start the server to check that everything is fine at this point:"

“At this point” would sound too repetitive second time in the same paragraph. Otherwise, done.

docs/tutorial/dependencies.adoc, line 30 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> You could use the [replaceable] style here for fillable values. You just need to use it very carefully, and possibly quite brackets with +++:
>
> ```
> [source, json, subs="normal"]
> .bower.json
> ----
> {
>   "name": "[replaceable]#my-project#",
>   "description": "",
>   "main": "",
>   "authors": +++[+++
>     "[replaceable]#Your Name#"+++]+++
> ```

Done.

docs/tutorial/dependencies.adoc, line 53 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Also here, using [replaceable] for version numbers and such would maybe clarify.

It doesn't really make sense to replace the version numbers here.
The version numbers in this file are declared in a flexible matter. The future minor and maintenance releases are also accepted.
At the same time, the major releases are not accepted to keep the tutorial working.

docs/tutorial/dependencies.adoc, line 55 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * There's no such file following this paragraph, so I don't know what file it refers to.
> * "this command" -> "the following command" (I hope there wasn't a confusion with my earlier correction to word "this" here)

Done.

docs/tutorial/dependencies.adoc, line 62 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "have the" -> "have a" (the directory is mentioned for the first time and is not always the same)

Done.

docs/tutorial/dependencies.adoc, line 106 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> Source control with Git was earlier removed by removing the .git directoryfrom the QuickStart project. so this only has effect once it's again initialized for Git. Maybe rephrase this a bit.

Done.

docs/tutorial/dependencies.adoc, line 108 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Maybe rather "Please" -> "You can".
> * "also" looks a bit unnecessary there

Done.

docs/tutorial/dependencies.adoc, line 116 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Maybe again write npm in lower case here, as it's a name (and identifier) that starts with lower case.

Done.

docs/tutorial/hero-editor.adoc, line 4 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Use serial comma in the list: "details, and"

Done.

docs/tutorial/hero-editor.adoc, line 9 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Add comma: "Therefore, "
> * "here" is an adverb that should usually go elsewhere... Can't decide how it should be so just let it be.
> * "in both" -> "both in"
> * "like" -> "such as"

Done.

docs/tutorial/hero-editor.adoc, line 11 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "explanations" ... or maybe it should be "for a detailed explanation of" (the tutorial itself is singular)

Done.

docs/tutorial/hero-editor.adoc, line 16 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * The getHero() method hasn't been mentioned or defined earlier, so the article probably should be indefinite (a).
> * No comma before "that", but then it comes ambiguous. Rather split the sentence: ". It can be used to retrieve"
>

Done.

docs/tutorial/hero-editor.adoc, line 42 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "the file" -> "a file with name"
> * "place these" -> "put the following"
> * "inside" -> "in it"

Done.

docs/tutorial/hero-editor.adoc, line 88 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "Vaadin DatePicker" doesn't seem like the proper product name (camelcase DatePicker looks like a Java class name). Its docs page has title "Date Picker", but otherwise `[vaadinelement]#vaadin-date-picker#` seems to be used everywhere. Maybe use the element name here as well, like you do for the `paper-input`.
> * Comma missing: "_property, this time_" (assuming that it was done earlier with one-way or no data binding)
> * Don't use latin abbreviations: i.e. -> "_(that is, with the_" (notice the missing article).

Done.

docs/tutorial/hero-editor.adoc, line 90 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "hero id" – Write "ID" capitalized when you use it as abbreviation for "identifier" ("id" is more like some psychoanalysis stuff...), unless you are referring to a property or variable name, in which case the appropriate style should be used. I suppose you could use either way here.

Done.

docs/tutorial/hero-editor.adoc, line 92 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * subproperty -> sub-property
> * subproperties -> sub-properties
> * Rather long sentence. You can split it at: "..._elements. When the user..._"

Done.

docs/tutorial/hero-editor.adoc, line 97 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * What's the `i>s`there? Looks like typo.
> * sub-properties
> * "moment" sounds a bit too exact point in time -> time

Done.

docs/tutorial/hero-editor.adoc, line 99 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * article: "_wrap the_"
> * sub-properties

Done.

docs/tutorial/hero-editor.adoc, line 102 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Don't use contractions such as don't. You could say "do not" or rephrase a bit, for example: "we want to avoid our editor contents from touching the edges"
> * Same with "it's"
> * Comma missing after introductory phrase: "_For that reason, we_"

Done.

docs/tutorial/hero-editor.adoc, line 106 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * `[elementname]#head#`

Done.

docs/tutorial/hero-editor.adoc, line 114 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Maybe rather: "_Next, we add_"
> * Serial comma missing: "_back button, and navigation reaction_"

Done.

docs/tutorial/hero-editor.adoc, line 208 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Article missing: "_Now we import the_" (the [identifier] decorator)
> * Article missing: "_We also add the_" (the [identifier] import)

Done.

docs/tutorial/hero-editor.adoc, line 210 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Probably extra article -> "_with routing_".

Done.

docs/tutorial/hero-editor.adoc, line 212 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "_We use the_" (the...decorator)
> * Use colon rather than comma to introduce a list
> * There should be no comma before "and"

Done.

docs/tutorial/hero-editor.adoc, line 214 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "route has the" (the...option)

Done.

docs/tutorial/hero-editor.adoc, line 220 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * plural missing? "hero details"?
> * The sentence is a bit complex, but maybe not too much.

Done.

docs/tutorial/hero-editor.adoc, line 283 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Article missing: "In _the_ listener method"
> * Serial comma missing: "_item, and_"

Done.

docs/tutorial/hero-editor.adoc, line 289 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "detail view" – I think in master-detail views, the detail are usually plural (there's more that one) and the views named in plural form. Hence, I'd rather use "details view" (also elsewhere in the tutorial). Also the Angular 2 tutorial seems to use that, but is not very consistent about it. In some cases it's OK to use singular, such as "hero detail data" .

Done.

docs/tutorial/hero-editor.adoc, line 292 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * You don't usually need to say that an image is a screenshot or such. (Think of a picture in a newspaper with title starting "Picture of ...")
> * Article missing, and figure titles should no longer be capitalized: "_The_ hero detail view"
>

Done.

docs/tutorial/hero-editor.adoc, line 299 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "Here" is a bit improper reference to the section itself. Maybe rather: "In the following, we go through and explain all the UX-related changes that were made to the AppComponent class earlier."
> * AppComponent is a class, so use [classname] like elsewhere

Done.

docs/tutorial/hero-editor.adoc, line 303 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> The "Nice Touches" section appears to be about changes that we did earlier, so it's more proper to use past rather than present tense.
> * "We added...", "bound", etc. This applies to many verbs in the entire "Nice Touches" section (though not all).

Done.

docs/tutorial/hero-editor.adoc, line 305 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Maybe rather: "dispatched so _that_".
> * Maybe "will be updated"  should be used, as it will happen after the event is dispatched.

Done.

docs/tutorial/hero-editor.adoc, line 309 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * ...use the past tense here as well... added
> * Article: "calls _the_ ... method"
> * Article: "invoke _the_ ... method"
> * "hero details" again here. The plural really fits here (and most other cases) much better than singular.

Done.

docs/tutorial/hero-editor.adoc, line 311 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * (No need for past tense in the first sentence)  .... (later) added

Done.

docs/tutorial/hero-editor.adoc, line 317 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Made, bound, added
> * Comma after introductory phrase: "For this purpose, we bound"

Done.

docs/tutorial/introduction.adoc, line 8 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "we will to" -> "we show how to" (maybe not necessary to use future here)
> * "we'll" -> "we will"

Done.

docs/tutorial/introduction.adoc, line 14 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * "please" -> "we advice you to"
> * "we are going to skip" -> "we skip"
> * Article missing: "given in _the_"

Done.

docs/tutorial/introduction.adoc, line 24 [r6] (raw file):
Previously, magi42 (Marko Grönroos) wrote…
> * Is "Paper Input" a valid product name? At least paper-input documentation only seems to talk about the `paper-input` element (use [elementname]).
> * Same for Vaadin Date Picker (which is used once in the documentation title, but otherwise [vaadinelement]#vaadin-date-picker# is used.
> * Note again the "hero detail" vs "details" in this file

Done.

docs/tutorial/layout.adoc, line 4 [r6] (raw file):