-
Notifications
You must be signed in to change notification settings - Fork 877
[WIP] docs(toh): copyedits to conform to Google doc standards (#3032) #3077
Conversation
There was a problem hiding this 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>. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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>. |
There was a problem hiding this comment.
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? |
There was a problem hiding this comment.
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.
423d23e
to
25ad010
Compare
There was a problem hiding this 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>. |
There was a problem hiding this comment.
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: a `title` property for the application name and a `hero` property | ||
for a hero named "Windstorm". | ||
## Show your hero |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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
andhero
property values, as strings, inside the HTML header tags.
Now that we have a `Hero` class, let’s refactor our component’s `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." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
with an
id
of1
It's important that the dev not spell it "ID"!
Now that we have a `Hero` class, let’s refactor our component’s `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." |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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).
674904f
to
4fcd3e5
Compare
There was a problem hiding this 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. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 tongFor
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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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=".") |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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 typeHero
.
: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. |
There was a problem hiding this comment.
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 theHero
class which is still in theapp.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. |
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
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
5357238
to
cb09c82
Compare
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 |
1 similar comment
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 |
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. |
Tour of Heroes copyedits
Rebase and conflict resolution for PR #3032 (which this closes).
Ward review
Todo
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.