Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

[WIP] docs(toh): copyedits to conform to Google doc standards (#3032) #3077

Merged
merged 2 commits into from
Mar 21, 2017

Conversation

wardbell
Copy link
Contributor

@wardbell wardbell commented Jan 5, 2017

Tour of Heroes copyedits
Rebase and conflict resolution for PR #3032 (which this closes).

Ward review

  • ToH-index
  • ToH-1
  • ToH-2
  • ToH-3
  • ToH-4
  • ToH-5
  • ToH-6

Todo

  • Reshoot intro graphics to show the ToH as it is today.

Merging this incomplete PR because we need the code-snippets changes in ToH 1 & 2 to land for aio.

@kapunahelewong will begin a new PR that picks up from the unfinished work here.

@wardbell wardbell changed the title [WIP} docs(toh): copyedits TOH-5 and TOH-6 (#3032) [WIP] docs(toh): copyedits TOH-5 and TOH-6 (#3032) Jan 5, 2017
@wardbell wardbell changed the title [WIP] docs(toh): copyedits TOH-5 and TOH-6 (#3032) [WIP] docs(toh): copyedits (#3032) Jan 5, 2017
@wardbell wardbell changed the title [WIP] docs(toh): copyedits (#3032) [WIP] docs(toh): copyedits to conform to Google doc standards (#3032) Jan 5, 2017
Copy link
Contributor Author

@wardbell wardbell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ToH-intro reviewed. On to the next.

You'll cover a lot of ground at an introductory level, and you'll find many links
to pages with greater depth.

When you're done with this tutorial, the app will look like this <live-example name="toh-6"></live-example>.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could say that it looks like the live example. We usually explain that you can run the sample in a live coding environment and download the code from there.

Can you rephrase to that effect?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I could say something like this:

You can run the live example of the app in a live coding environment and download the code from there.

I don't like that "live" appears twice, but it looks like "live example" is the hard-coded label for the link. Is there a way to change the text?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's just call it plunker. "People know what it is (we've told them). You can run the live example of the app in plunker and download the code from there."

Clicking the "Back" button would return us to the "Dashboard".
Links at the top can take us to either of the main views.
We'll click "Heroes". The app takes to the "Heroes" master list view.
Clicking the "Back" button returns users to the Dashboard.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels wooden and alternates between singular user to plural users/them.

Maybe should speak as if "you", the reader, are clicking through the app ... in which case this all becomes "you" rather than "users/they".

@@ -2,11 +2,11 @@ include ../_util-fns

:marked
## Setup to develop locally
Real application development takes place in a local development environment like your machine.
Application development takes place in a local development environment, like your machine.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

such as your machine

May be better to just cut this. Devs know what a "local environment" means.


Follow the [setup](../guide/setup.html) instructions for creating a new project
named <ngio-ex path="angular-tour-of-heroes"></ngio-ex>
after which the file structure should look like this:
named <ngio-ex path="angular-tour-of-heroes"></ngio-ex>.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, if you only followed the current setup instructions, there would be many more files. I just added a section to the Setup guide for deleting non-essential files. We should refer to that too.

See #3079 which will merge soon.

The link to it would be

 [_Deleting non-essential files_](../guide/setup.html#non-essential "Setup: Deleting non-essential files")


figure.image-display
img(src='/resources/images/devguide/toh/heroes-list-2.png' alt="Output of heroes list app")
// CF: The ability to add heroes isn't shown in the images or discussed in this page. Should that be added?
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a note in the "Todos" at the top of this PR that we need to review the images and the current state of the ToH app. These images were taken before ToH 6.

@wardbell wardbell force-pushed the cfranger-toh branch 2 times, most recently from 423d23e to 25ad010 Compare January 6, 2017 07:12
Copy link
Contributor Author

@wardbell wardbell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ToH-1 reviewed by me

@@ -23,27 +23,24 @@ include ../_util-fns
.file systemjs.config.js
.file tsconfig.json
:marked
When we're done with this first episode, the app runs like this <live-example></live-example>.
When you're done with this page, the app should look like this <live-example></live-example>.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See earlier comment in which I wonder whether "should look like this" adequately conveys the idea that the app can be run in plunker and downloaded from there.


Update the `AppComponent` so it has two properties: &nbsp; a `title` property for the application name and a `hero` property
for a hero named "Windstorm".
## Show your hero
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Show the hero

As I've been going from "we" to "you", I've found that going to "the" is often less jarring ... particularly when there is a parade of punishing "you"s. You seem to have felt the same way ... except here.

for a hero named "Windstorm".
## Show your hero
To display hero data in the app,
add two properties to the `AppComponent`: a `title` property for the app name and a `hero` property
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The title isn't about hero data. Maybe we should just strike "To display hero data in the app" and go right to the instruction.


The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
The double curly braces instruct the app to read the `title` and `hero` properties from the component and render them.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The double curly braces are Angular's interpolation binding syntax. These interpolation bindings present the component's title and hero property values, as strings, inside the HTML header tags.

Now that we have a `Hero` class, let’s refactor our components `hero` property to be of type `Hero`.
Then initialize it with an id of `1` and the name, "Windstorm".
In the `Hero` class, refactor the component's `hero` property to be of type `Hero`,
then initialize it with an ID of `1` and the name "Windstorm."
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with an id of 1

It's important that the dev not spell it "ID"!

Now that we have a `Hero` class, let’s refactor our components `hero` property to be of type `Hero`.
Then initialize it with an id of `1` and the name, "Windstorm".
In the `Hero` class, refactor the component's `hero` property to be of type `Hero`,
then initialize it with an ID of `1` and the name "Windstorm."
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, it should be 'Windstorm'. Period on the outside; not in the assigned string. Putting it in back-ticks (code font) will help.

We want to start the TypeScript compiler, have it watch for changes, and start our server.
Do this by entering the following command in the terminal window.

To start the TypeScript compiler in watch mode and start the server, type the following:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if people don't know what "watch mode" means? That's why we said "watch for changes". Probably should have said "watch for code changes".

I'm feeling this whole passage is a bit off. How about this?

  Enter the following command in the terminal window:
code-example(language="sh" class="code-shell").
  npm start

:marked
  That command runs the TypeScript compiler in "watch mode", recompiling automatically when the code changes.
  The command simultaneously launches the app in a browser and refreshes the browser when the code changes.

  You keep building the Tour of Heroes without pausing to re-compiling or refresh the browser.

add a `<div>` for the hero's `id` property and another `<div>` for the hero's `name`.
To keep the template readable, use the template strings feature
in ES2015 and TypeScript:
change the quotes around the template to backticks
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this was written, there is no need to "change the quotes ... to backticks". They already are backticks.

Not everyone will know about backticks or ES2015 strings yet so we should still call this out:

  To show all of the hero's properties,
  add a `<div>` for the hero's `id` property and another `<div>` for the hero's `name`.

  Keep the template readable by placing each `<div>` on its own line.
  The backticks around the component template let you 
  put the `<h1>`, `<h2>`, and `<div>` elements on their own lines, thanks to the
  <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals" target="_blank" title="template literal"><i>template literals</i></a>
  feature in ES2015 and TypeScript. 


+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'multi-line-strings', 'app.component.ts (AppComponent\'s template)')

.callout.is-important
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the link to template literals (as seen in my comment), we don't need this anymore.


We want to be able to edit the hero name in a textbox.
Users should be able to edit the hero name in a textbox.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part, where we show them the wrong way to do it, should be removed. It seemed useful at the time. But now I think it is a distraction and is more confusing than enlightening.

The fix here ... which also involves code changes (the snippets must go) ... is too hard to describe in github. So I'm adding a commit that makes JUST THESE CHANGES; the other feedback awaits your response.

The other problem (here and elsewhere) is that the label should surround the input box to be a11y compliant.
I think we should hold off on the a11y for another pass (it will be sweeping).

@wardbell wardbell force-pushed the cfranger-toh branch 3 times, most recently from 674904f to 4fcd3e5 Compare January 6, 2017 08:24
Copy link
Contributor Author

@wardbell wardbell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

End of ward's ToH-2 review

### Creating heroes
Let’s create an array of ten heroes.
## Displaying heroes
To display a list of heroes, you'll add the heroes to the view's template.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest dropping "the" from "add the heroes":

you'll add heroes to the ...

@@ -1,22 +1,17 @@
include ../_util-fns
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was so old that the sample still had a "snippets" file to source some of the doc region stuff. I thought we'd rid ourselves of all of them. Guess not. Well it's gone now as of the SECOND COMMIT I added that is dedicated to this purpose and a few formatting issues.

We could have defined the heroes list here in this component class.
But we know that ultimately we’ll get the heroes from a data service.
Because we know where we are heading, it makes sense to separate the hero data
from the class implementation from the start.
:marked
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section has to be indented 2 spaces in order to show. If fixed it in my SECOND COMMIT so that I could see your changes.

Our component has `heroes`. Let’s create an unordered list in our template to display them.
We’ll insert the following chunk of HTML below the title and above the hero details.
### Display hero names in a template
The component has `heroes`. To display the hero names in an unordered list,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest dropping the first sentence:

The component has heroes.


.alert.is-critical
:marked
The leading asterisk (`*`) in front of `ngFor` is a critical part of this syntax.
// CF: is a "critical" type note appropriate here? Could we merge this sentence with
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. We don't need this warning box. Just fold the thought into the first sentence of the sub-section

The (*) prefix to ngFor is a critical part of this syntax.
It indicates that the <li> element and its children
constitute a master template.

The `ngIf` keeps the selected hero detail out of the DOM as long as the `selectedHero` is undefined.
When you click a hero in the list, the selected hero displays in the hero details.

### Style the selection
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style the selected hero

The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` otherwise.
We’re saying “*apply the `selected` class if the heroes match, remove it if they don’t*”.
+makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'class-selected-1', 'app.component.ts (setting the CSS class)')(format=".")
The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` if they don't.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence was lost because there is no :marked in front of it.
But the sentence is also awful and should be deleted.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify, are you saying I should delete the sentence beginning with "The key is..."?

We’re saying “*apply the `selected` class if the heroes match, remove it if they don’t*”.
+makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'class-selected-1', 'app.component.ts (setting the CSS class)')(format=".")
The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` if they don't.
+makeExample('toh-2/ts/app/app.component.1.html', 'class-selected-1', 'app.component.ts (setting the CSS class)')(format=".")
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This +makeExample(...) is in the wrong place.

It belongs below the sub-section "Read more about ..."

It needs its own introductory sentence such as

The final version of the <li> looks like this:

The browser reloads our app.
We select the hero Magneta and the selection is clearly identified by the background color.
After the browser refreshes,
click the hero Magneta. The background color clearly identifies the selection.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

click the hero, "Magneta".

or better

click "Magneta".

The browser reloads our app.
We select the hero Magneta and the selection is clearly identified by the background color.
After the browser refreshes,
click the hero Magneta. The background color clearly identifies the selection.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... identifies your selection.

because YOU clicked it.

Copy link
Contributor Author

@wardbell wardbell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I started reviewing ToH-3 and eventually realized that it needed too much work to express in review comments.

Added a commit dedicated to fixing it.

Our app is growing.
Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable.
The app is growing.
Use cases arise for reusing components, passing data to components, and creating more reusable assets.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yuck. I don't like the original and not loving the update.

How about getting to the problem and the point of this page.

The AppComponent is doing everything at the moment. First it showed details of a single hero. Then it became a master/detail form with both a list of heroes and the hero detail. You can't keep piling new features into one component; that's not maintainable.

You'll want to break it up into other sub-components,each focused on a specific feature or workflow. Eventually, the AppComponent could become a simple shell that hosts those sub-components.

In this page, you'll take the first step in that direction by carving out the hero details into a separate, reusable component.

Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable.
The app is growing.
Use cases arise for reusing components, passing data to components, and creating more reusable assets.
On this page, you'll separate the heroes list from the hero details and make the details component reusable.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No longer needed if you like the new intro.

@@ -26,179 +28,179 @@ include ../_util-fns
.file systemjs.config.js
.file tsconfig.json
:marked
### Keep the app transpiling and running
We want to start the TypeScript compiler, have it watch for changes, and start our server. We'll do this by typing
## Keep the app transpiling and running
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reader should know the drill by now. We don't need a separate section for this. Just say.

Keep the app transpiling and running by entering the npm start command in a terminal window as you did before, and continue building the Tour of Heroes.

We'll need to go back to toh-pt1.jade and add a#keep-transpiling above that section so that the new link works.

Yet every change puts both components at risk and doubles the testing burden without benefit.
If we had to reuse the hero details elsewhere in our app,
the heroes list would tag along for the ride.
## Making a hero detail component
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make a hero detail component

especially if doing them right is easy and we learn how to build Angular apps in the process.

Let’s break the hero details out into its own component.
To comply with the
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's cut the theory ... and this link ... and the repeat of the motivation that I added at the top.

Let's cut this entire section ... straight through "Separate the hero detail component" and begin with ...

Add a file named ...

At the moment, the *Heroes* and *Hero Detail* views are combined in one template in `AppComponent`.
Let’s **cut** the *Hero Detail* content from `AppComponent` and **paste** it into the new template property of `HeroDetailComponent`.
### Hero detail template
To separate the *Heroes* and *Hero Detail* views,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions aren't quite correct. How about this rewrite?

  ### Hero detail template
  To move the hero detail view to the `HeroDetailComponent`,
  cut the hero detail _content_ from the `AppComponent` template
  and paste it into a new `template` property in the `@Component` metadata.

  The `HeroDetailComponent` has a _hero_, not a _selected hero_. 
  So replace the word _selectedHero_ with _hero_ everywhere in the template.
  When you're done, the new template should look like this:

Let’s add that `hero` property we were talking about to the component class.
+makeExample('toh-3/ts/app/hero-detail.component.ts', 'hero')
### Add the *hero* property
Add the earlier mentioned `hero` property to the component class.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template binds to a hero property. Add that property to the component class, giving it the type Hero.

:marked
Uh oh. We declared the `hero` property as type `Hero` but our `Hero` class is over in the `app.component.ts` file.
We have two components, each in their own file, that need to reference the `Hero` class.
You may notice that the `hero` property is declared as type `Hero` but the `Hero` class is in the `app.component.ts` file.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hero property refers to the Hero class which is still in the app.component.ts file.


+makeExample('toh-3/ts/app/hero.ts', '', 'app/hero.ts')(format=".")

:marked
We export the `Hero` class from `hero.ts` because we'll need to reference it in both component files.
Add the following import statement near the top of **both `app.component.ts` and `hero-detail.component.ts`**.
The `Hero` class is exported from `hero.ts` because it is referenced in both component files.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete this sentence. We just said that.

We export the `Hero` class from `hero.ts` because we'll need to reference it in both component files.
Add the following import statement near the top of **both `app.component.ts` and `hero-detail.component.ts`**.
The `Hero` class is exported from `hero.ts` because it is referenced in both component files.
Add the following import statement near the top of *both* `app.component.ts` and `hero-detail.component.ts`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that the Hero class is in its own file, the AppComponent and the HeroDetailComponent have to import it.
Add the following imports statement near the top of the app.component.ts and hero-detail.component.ts files.

Additional updates based on Ward's feedback, and more comments after I went through the last two pages of the tutorial.

docs(toh-2): replace snippets file; indent subsection; add (format='.').

docs(toh-1): code sample changes by Ward

docs(toh): copyedits to conform to Google doc standards
continues and closes PR angular#3032
@googlebot
Copy link

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

1 similar comment
@googlebot
Copy link

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that they're okay with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

@wardbell
Copy link
Contributor Author

Merging this incomplete PR because we need the code-snippets changes in ToH 1 & 2 to land for aio.

@kapunahelewong will begin a new PR that picks up from the unfinished work here.

@wardbell wardbell merged commit 0fc4028 into angular:master Mar 21, 2017
@wardbell wardbell deleted the cfranger-toh branch March 21, 2017 18:08
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants