[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

cfranger · 2016-10-27T19:15:42Z

This is a pull request for initial review. Do not merge.

naomiblack · 2016-10-27T19:17:41Z

public/docs/ts/latest/tutorial/toh-pt1.jade

@@ -32,80 +30,83 @@ include ../_quickstart_repo
    .file typings.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
+  Type the following command:



This is taking a little too much away. It's important for the reader to know why they are entering the command.

… see my comments starting with "CF:"

wardbell · 2016-10-29T00:58:29Z

Looks like @naomiblack has you covered on this. Let me know when/if it's appropriate for me to review.

cfranger · 2016-10-29T01:19:04Z

@naomiblack I did a more thorough pass on the first two tutorial lessons. Would you, @kwalrath , @kapunahelewong , or Shannon (can't find her handle) review my edits?

kapunahelewong · 2016-10-31T15:11:46Z

public/docs/ts/latest/tutorial/toh-pt1.jade


-  Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
+  **Try it out**. Here's a link to a <live-example></live-example>.


I'd probably strike "Try it out", though it's better because it's shorter and more to the point than the original. How about something like what's on the Architecture page?

"The code referenced on this page is available as a live example."

kapunahelewong · 2016-10-31T15:13:27Z

public/docs/ts/latest/tutorial/toh-pt1.jade


  +makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero')

  :marked
-    The browser should refresh and display our title and hero.
+    The browser refreshes and display the title and hero name.


"and displays"

kapunahelewong · 2016-10-31T15:15:36Z

public/docs/ts/latest/tutorial/toh-pt1.jade

 :marked
  ### Hero object

-  At the moment, our hero is just a name.  Our hero needs more properties.
+  Our hero needs more properties.


Do a global search for "our", "we", "let's", and "us". You want to get rid of all first person. Ideally, we want to minimize second person, too.

kapunahelewong · 2016-10-31T17:38:58Z

public/docs/ts/latest/tutorial/toh-pt1.jade


 +makeExample('toh-1/ts/app/app.component.ts', 'hero-class-1', 'app.component.ts (Hero class)')(format=".")

 :marked
-  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".
+  Now in your `Hero` class, refactor the component's `hero` property to be of type `Hero`,


I'd change "Now in your" to "In the"

kapunahelewong · 2016-10-31T17:47:08Z

public/docs/ts/latest/tutorial/toh-pt1.jade

-  Change the quotes around the template to back-ticks and
-  put the `<h1>`, `<h2>` and `<div>` elements on their own lines.
+  Displaying a name is good, but we want to see all of the hero's properties.
+  For this update, you'll add a `<div>` for the hero's `id` property and another `<div>` for the hero's `name`.


In this and the following sentence, remove the future tense (two instance of "you'll"). Sometimes "you can" works. For the sentence "Displaying a name is good...", you could remove it altogether, turn it into a phrase and start the next sentence with it. For example, "To show all of the hero's properties, you can...".

kapunahelewong · 2016-10-31T17:54:38Z

public/docs/ts/latest/tutorial/toh-pt1.jade


 .l-main-section
 :marked
-  ## Editing Our Hero
+  ## Editing the hero name

  We want to be able to edit the hero name in a textbox.


I'd get rid of "We want to be able to" and make it more direct. I might even delete the sentence altogether and use the idea to introduce the next sentence.

"To edit the hero name in a textbox, refactor..."

kapunahelewong · 2016-10-31T17:55:21Z

public/docs/ts/latest/tutorial/toh-pt1.jade


  We want to be able to edit the hero name in a textbox.

-  Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown below:
+  Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown:


I'd delete "as shown" since that's implied by the use of the colon.

kapunahelewong · 2016-10-31T18:09:18Z

public/docs/ts/latest/tutorial/toh-pt1.jade

+  The hero's name now appears in the `<input>` textbox.
+  But if you change the name, you'll notice that your change
+  isn't reflected in the `<h2>`. To get the desired behavior,
+  you'll implement two-way binding to `<input>`.


Change you'll to "you can" or reword making it a clear bridge to the next section. I'd even look for a way of getting rid of "you" here. You could do a number of things here like incorporating the imperative or rewording/condensing. Here's a possibility:

"The hero's name now appears in the textbox but the h2 doesn't reflect changes without two-way binding."

kapunahelewong · 2016-10-31T18:12:00Z

public/docs/ts/latest/tutorial/toh-pt1.jade

-  of external modules used by our application.
-  Now we have included the forms package which includes `ngModel`.
+  Before using two-way data binding for **form inputs**, import the `FormsModule`
+  package in your Angular module. Add the `FormsModule` to the `NgModule` decorator's `imports` array, which contains the list


your -> the

kapunahelewong · 2016-10-31T18:16:27Z

public/docs/ts/latest/tutorial/toh-pt1.jade

+  using the built-in `ngModel` directive. This binding both displays the hero's name and allows users to change it.
+  * The `ngModel` directive propagates changes to every other binding of the `hero.name`.
+
+  **Try it out**. Here's a link to a <live-example></live-example>.


I prefer the way this sentence was originally since we don't need to specify that it's a link. That should be clear by the styles. We don't want it to read like "click here for more".

I'd check globally for consistency on this point whichever way you go on it.

kapunahelewong · 2016-10-31T18:21:49Z

public/docs/ts/latest/tutorial/toh-pt2.jade

-  We aspire to fetch this list of heroes from a web service, but let’s take small steps
-  first and display mock heroes.
+  The `HEROES` array is of type `Hero`, the class defined in the previous page.
+  We aspire to fetch the list of heroes from a web service, but you'll take small steps


Same goes for "we" in this file as in part one. I won't note it each time since you know now.

kapunahelewong · 2016-10-31T18:25:11Z

public/docs/ts/latest/tutorial/toh-pt2.jade

-    Because we know where we are heading, it makes sense to separate the hero data
+    You could define the heroes list in the component class,
+    but ultimately you'll get the heroes from a data service.
+    Because we know where we're heading, it makes sense to separate the hero data
    from the class implementation from the start.


Maybe reword to something like:

"It makes sense to separate the hero data from the class implementation from the start because ultimately the heroes will come from a data service."

kapunahelewong · 2016-10-31T18:27:22Z

public/docs/ts/latest/tutorial/toh-pt2.jade

  and display them individually.
-  We’ll need some help from Angular to do this. Let’s do this step by step.
+  You'll need some help from Angular to do this.


This sentence could be deleted.

kapunahelewong · 2016-10-31T18:37:13Z

public/docs/ts/latest/tutorial/toh-pt2.jade


-  That's a lot of styles! We can put them inline as shown here, or we can move them out to their own file which will make it easier to code our component. 
-  We'll do this in a later chapter. For now let's keep rolling.
+  That's a lot of styles! In a later page, you'll move the styles to a separate file. 


"That's a lot of styles!" is a conversational style we've been working to reduce. I'd take it out and reword the sentence immediately afterward to include that idea.

kapunahelewong · 2016-10-31T18:37:51Z

public/docs/ts/latest/tutorial/toh-pt2.jade


-  Our template for displaying the heroes should now look like this:
+  Your template for displaying the heroes should look like this:


Your -> The. I'd do this anywhere you can.

kapunahelewong · 2016-10-31T18:43:03Z

public/docs/ts/latest/tutorial/toh-pt2.jade

  .l-sub-section
    :marked
-      Learn more about Event Binding in the 
+      Learn more about event binding in the 


We're trying to move away from "Learn more" to wording like "Read more".

kapunahelewong · 2016-10-31T18:48:33Z

public/docs/ts/latest/tutorial/toh-pt2.jade

+    anywhere in this section without commenting out the rest of the section and the next section.)
+    This section title is a verb, making it sound like a task, but it's really an introduction;
+    the tasks it discusses aren't performed until the next section. Would it make sense to merge
+    the two sections and maybe change the title to "Add a click handle to expose the selected hero"? -->


Yes, I think that makes sense. This section really is just a very short intro that could be reduced (because of the conversational style) and then put in the next section.

kapunahelewong · 2016-10-31T18:49:52Z

public/docs/ts/latest/tutorial/toh-pt2.jade


  +makeExample('toh-2/ts/app/app.component.ts', 'selected-hero', 'app.component.ts (selectedHero)')
-
+  // CF: here I noticed that the hero names disappeared. Would it be helpful to mention that?


Yes, it is helpful. I'd pull back on the conversational style of how you say it, though.

kapunahelewong · 2016-10-31T19:22:03Z

public/docs/ts/latest/tutorial/toh-pt2.jade


-    We'll address this problem by keeping the hero detail out of the DOM until there is a selected hero.
+    To address this issue, you'll keep the hero detail out of the DOM until there is a selected hero.
+    <!-- CF: Will readers know what "DOM" means? -->


Yes, they should. Check out this guide for assumptions about the reader. DevGuide for Authors

kapunahelewong · 2016-10-31T19:47:44Z

public/docs/ts/latest/tutorial/toh-pt2.jade


  +makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'ng-if', 'app.component.ts (ngIf)')
+  // CF: Would it be helpful to note that now the list of names reappears in the browser?


Yes it would be helpful.

kapunahelewong · 2016-10-31T20:04:17Z

public/docs/ts/latest/tutorial/toh-pt2.jade


  .alert.is-critical
    :marked
      Remember that the leading asterisk (`*`) in front of `ngIf` is
      a critical part of this syntax.
+  //  CF: is a "critical" type note appropriate here? Could I merge this sentence with
+    the next section?


Hm, not sure. I've seen this same treatment in a couple of places and I think there's a particular reason behind it. I'm going to have to defer to @kwalrath on this one.

kapunahelewong · 2016-10-31T20:25:12Z

public/docs/ts/latest/tutorial/toh-pt2.jade

+  ## The road ahead
+  Your Tour of Heroes app has grown, but it's far from complete.
+  You can't put the entire app into a single component.
+  <!-- CF: It's not clear to me why you can't put it into a single component. Is this sentence necessary? -->


As the app grows (especially in the case of a real world production app), the components can get really big and sometimes one can need changes that another doesn't, so if you separate them from one another, you have a lot more flexibility and maintenance is easier. You also have an easier time troubleshooting bugs because you're likely to be able to narrow it down to a specific chunk of code. In this particular example, the app is very small so technically, here, it's not that big of a deal to keep it in one component, but as an app grows, it becomes of paramount importance. Part of what we're doing in the docs is guiding the structure of the project toward that more flexible solution. Does that help?

kapunahelewong · 2016-10-31T20:36:08Z

public/docs/ts/latest/tutorial/toh-pt1.jade


-  ### Multi-line template strings
+  ### Adding HTML with multi-line template strings


What's your thought process on the headlines? (Maybe I've missed something - are we standardizing the grammar on them?)

cfranger · 2016-11-03T17:47:13Z

public/docs/ts/latest/tutorial/toh-pt2.jade

+  verify that you have the following structure after [Part 1](./toh-pt1.html).
+  If not, you'll need to go back to Part 1 and figure out what you missed.
+// CF: In the left nav bar, "Part 1" is numbered "2" and "Part 2" is numbered "3,"
+ so referring to "Part 1" etc. could be confusing.


Instead of referring to "part" numbers, would it be better to use "the previous page", "this page", etc? or the page name?

cfranger · 2016-11-03T17:48:01Z

public/docs/ts/latest/tutorial/toh-pt2.jade

+  Create an array of ten heroes.
+//  CF: I don't see a rule in the Angular Writing Guidelines for task titles. Is there a 
+  preference for using gerunds ("Creating heroes") or imperatives ("Create heroes")?
+  Both styles are used in this tutorial.


Any recommendations for gerunds vs. imperatives?

Initial edits with several questions for Naomi and Ward.

f34cecd

googlebot added the CLA: yes label Oct 27, 2016

naomiblack reviewed Oct 27, 2016

View reviewed changes

cfranger added 4 commits October 27, 2016 12:39

WIP: testing push

4251e8c

WIP: added "CF: " to my comments/questions

7a6ad3b

WIP: 10/27 updates

da4e27d

WIP: full edit pass on these pages, as well as some questions. Please…

c546dac

… see my comments starting with "CF:"

kapunahelewong reviewed Oct 31, 2016

View reviewed changes

cfranger commented Nov 3, 2016

View reviewed changes

wardbell changed the title ~~WIP: Initial edits with several questions for Naomi and Ward.~~ [WIP] docs(toh): Initial edits with several questions for Naomi and Ward. Nov 14, 2016

cfranger mentioned this pull request Dec 23, 2016

[WIP] Rebase for final edits #3032

Closed

cfranger closed this Dec 23, 2016

cfranger deleted the CFranger-tutorial-copyedits branch January 27, 2017 18:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

cfranger commented Oct 27, 2016

naomiblack Oct 27, 2016

wardbell commented Oct 29, 2016

cfranger commented Oct 29, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016 •

edited

Loading

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016 •

edited

Loading

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016 •

edited

Loading

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

kapunahelewong Oct 31, 2016

cfranger Nov 3, 2016

cfranger Nov 3, 2016


		Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
		Try it out. Here's a link to a <live-example></live-example>.


		Our template for displaying the heroes should now look like this:
		Your template for displaying the heroes should look like this:


		+makeExample('toh-2/ts/app/app.component.ts', 'selected-hero', 'app.component.ts (selectedHero)')

		// CF: here I noticed that the hero names disappeared. Would it be helpful to mention that?


		+makeExample('toh-2/ts-snippets/app.component.snippets.pt2.ts', 'ng-if', 'app.component.ts (ngIf)')
		// CF: Would it be helpful to note that now the list of names reappears in the browser?


		### Multi-line template strings
		### Adding HTML with multi-line template strings

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

Conversation

cfranger commented Oct 27, 2016

Choose a reason for hiding this comment

wardbell commented Oct 29, 2016

cfranger commented Oct 29, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kapunahelewong Oct 31, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kapunahelewong Oct 31, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kapunahelewong Oct 31, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kapunahelewong Oct 31, 2016 •

edited

Loading

kapunahelewong Oct 31, 2016 •

edited

Loading

kapunahelewong Oct 31, 2016 •

edited

Loading