docs(Displaying Data): copy edits #2435

kapunahelewong · 2016-09-21T18:22:09Z

Copy edits in guide/_data.json and displaying-data.jade.

kwalrath · 2016-09-21T21:20:34Z

public/docs/ts/latest/guide/_data.json

@@ -17,7 +17,7 @@

  "displaying-data": {
    "title": "Displaying Data",
-    "intro": "Interpolation and other forms of property binding help us show app data in the UI.",
+    "intro": "Property binding shows app data in the UI.",


Hmmm... I wouldn't say the binding shows it, it just enables showing it. Can you reword this?

Changed to: "Property binding helps show app data in the UI."

kwalrath · 2016-09-21T21:21:55Z

public/docs/ts/latest/guide/displaying-data.jade

 :marked
-  We typically display data in Angular by binding controls in an HTML template
+  Angular typically displays data by binding controls in an HTML template


This changes the meaning. The dev specifies the binding, which enables the app to display property values. Can you think of another way to say this?

kwalrath · 2016-09-21T21:22:56Z

public/docs/ts/latest/guide/displaying-data.jade

@@ -17,42 +17,42 @@ figure.image-display
  img(src="/resources/images/devguide/displaying-data/final.png" alt="Final UI")

 :marked
-  # Table Of Contents
+  # Contents


Do we usually use a first-level heading for Contents? (I'm actually not sure. I tend not to in my own writing, but I don't remember whether we've established a good precedent in these pages.)

Good question. I did a global search and found that in readme files we tend toward ## but in the jade files we use #. I'll keep an eye out for consistency.

kwalrath · 2016-09-21T21:25:17Z

public/docs/ts/latest/guide/displaying-data.jade

-      much more readable HTML.
+      The backtick (<code>\`</code>)&mdash;which is *not* the same character as a single
+      quote (`'`)&mdash;allows you to compose a string over several lines, which makes
+      HTML more readable.


HTML -> the HTML
?
(It sounded funny to me.)

kwalrath · 2016-09-21T21:27:44Z

public/docs/ts/latest/guide/displaying-data.jade

-    the view such as a keystroke, a timer completion, or an async `XHR` response.
-    We don't have those in this sample.
-    But then the properties aren't changing on their own either. For the moment we must operate on faith.
+    the view, such as a keystroke, a timer completion, or an async `XHR` response.


Why is XHR in code font? I don't think it's a string you'll see in any code. Also, you already said "asynchronous" before, so "async" seems unnecessary. Maybe:

...a response to an HTTP request.

kwalrath · 2016-09-21T21:46:49Z

public/docs/ts/latest/guide/displaying-data.jade

-    This is a wonderfully concise and compact technique.
-
-    Some folks prefer to declare the properties and initialize them within a constructor like this:
+    You initialized your component properties using variable assignment. You could have


I'm not crazy about "you" here, since they didn't make the decision. Can you think of a better way to phrase this?

kwalrath · 2016-09-21T21:48:08Z

public/docs/ts/latest/guide/displaying-data.jade

-    That's fine too. The choice is a matter of taste and organization policy.
-    We'll adopt the more terse "variable assignment" style in this chapter simply because
-    there will be less code to read.
+    This page demonstrates the more terse "variable assignment" style simply for


Ward mentioned using "chapter" instead of "page" because "page" can be confused with the app. This is the first time I've noticed that problem, although I don't think it matters too much in this case which one you mean. Maybe:

This app uses the more terse...

Good point. Changed.

kwalrath · 2016-09-21T21:49:25Z

public/docs/ts/latest/guide/displaying-data.jade

  each item in the `heroes` list.

 +makeExcerpt('app/app.component.2.ts', 'template')

 :marked
-  Our presentation is the familiar HTML unordered list with `<ul>` and `<li>` tags. Let's focus on the `<li>` tag.
+  This presentation uses the HTML unordered list with `<ul>` and `<li>` tags. The `*ngFor`


presentation -> UI
?

Agreed. Done.

kwalrath · 2016-09-21T21:50:47Z

public/docs/ts/latest/guide/displaying-data.jade

-  it is an example of a [template input variable](./template-syntax.html#ngForMicrosyntax).
+  it is an example of a template input variable. Read
+  more about template input variables in the [microsyntax](./template-syntax.html#ngForMicrosyntax) section of
+  the [Template Syntax](./template-syntax.html) page.


good x-ref!

Thanks! That one took me a minute to sort out. :)

kwalrath · 2016-09-21T21:52:14Z

public/docs/ts/latest/guide/displaying-data.jade

-  We are defining our data directly inside our component.
-  That's fine for a demo but certainly isn't a best practice. It's not even a good practice.
-  Although we won't do anything about that in this chapter, we'll make a mental note to fix this down the road.
+  You are defining your data directly inside the component which isn't best practice.


which -> , which

(as a rule, use either "that" or ", which", depending on whether the phrase is restrictive—can't be dropped without changing the meaning—or nonrestrictive)

"you" sounds a little accusatory here. Maybe:

This app's code defines the data directly inside the component, which...

kwalrath

You input the editor's changes well, but I think we need to use "you" much less often. Also, in many cases the editor changed intros to something that looked like a command.

kwalrath · 2016-09-21T21:54:01Z

public/docs/ts/latest/guide/displaying-data.jade

-  That's fine for a demo but certainly isn't a best practice. It's not even a good practice.
-  Although we won't do anything about that in this chapter, we'll make a mental note to fix this down the road.
+  You are defining your data directly inside the component which isn't best practice.
+  For illustrative purposes, however, it's fine.


Not sure that "illustrative purposes" is the best phrase here. Maybe... "a simple demo"?

kwalrath · 2016-09-21T21:54:50Z

public/docs/ts/latest/guide/displaying-data.jade

-  most of the time we're binding to more specialized objects.
-
-  Let's turn our !{_array} of hero names into !{_an} !{_array} of `Hero` objects. For that we'll need a `Hero` class.
+  At the moment, you're binding to !{_an} !{_array} of strings.


Again, the "you" seems unnecessary here. Maybe:

you're binding -> the data binding is

kwalrath · 2016-09-21T23:52:53Z

public/docs/ts/latest/guide/displaying-data.jade

-
-  Let's turn our !{_array} of hero names into !{_an} !{_array} of `Hero` objects. For that we'll need a `Hero` class.
+  At the moment, you're binding to !{_an} !{_array} of strings.
+  Most of the time you'd bind to more specialized objects. To do this, turn your !{_array}


Most of the time you'd bind to
->
In real applications, most bindings are to

To do this, ...
->
(new paragraph)
To convert this binding to use specialized objects,
turn the !{_array}...

kwalrath · 2016-09-21T23:54:04Z

public/docs/ts/latest/guide/displaying-data.jade


-    It might not look like we have properties, but we do. We're taking
-    advantage of a TypeScript shortcut in our declaration of the constructor parameters.
+    It might not look like you have properties, but you do. You're taking


Let's do more de-you-ification:

you have -> the class has
you do -> it does

kwalrath · 2016-09-21T23:55:26Z

public/docs/ts/latest/guide/displaying-data.jade

-    It might not look like we have properties, but we do. We're taking
-    advantage of a TypeScript shortcut in our declaration of the constructor parameters.
+    It might not look like you have properties, but you do. You're taking
+    advantage of a TypeScript shortcut in your declaration of the constructor parameters.


Change this last sentence to avoid the "your":

The declaration ... parameters takes advantage of ... shortcut.

kwalrath · 2016-09-21T23:59:59Z

public/docs/ts/latest/guide/displaying-data.jade

  At the moment it displays the hero's `id` and `name`.
-  Let's fix that so we display only the hero's `name` property.
+  Fix that so you display only the hero's `name` property.


so you -> to

kwalrath · 2016-09-22T00:02:08Z

public/docs/ts/latest/guide/displaying-data.jade


 +makeExcerpt('app/app.component.3.ts', 'template')

 :marked
-  Our display looks the same, but now we know much better what a hero really is.
+  Your display looks the same, but now you've clarified what a hero is.


Your -> The
now you've clarified ... is -> the code is clearer.

kwalrath · 2016-09-22T00:04:36Z

public/docs/ts/latest/guide/displaying-data.jade


 .l-main-section#ngIf
 :marked
  ## Conditional display with NgIf

  Sometimes an app needs to display a view or a portion of a view only under specific circumstances.

-  In our example, we'd like to display a message if we have a large number of heroes, say, more than 3.
+  In the example, you can display a message if there are more than three heroes.


"you can" seems misleading here. The point is not what you can do, but that you're going to do it conditionally. Maybe:

Let's change the example to display...

(I know, that uses "us", but I can't think of a clearer way to introduce what's coming next. Maybe you can!)

Confession...I love "let's"! :D
Done.

kwalrath · 2016-09-22T00:06:28Z

public/docs/ts/latest/guide/displaying-data.jade

-    That hardly matters here. But it would matter a great deal, from a performance perspective, if
-    we were conditionally including or excluding a big chunk of HTML with many data bindings.
+    Angular isn't showing and hiding the message. It is adding and removing the paragraph element from the DOM
+    which improves performance, especially in larger projects when conditionally including or excluding


DOM which -> DOM. That

kwalrath · 2016-09-22T00:06:54Z

public/docs/ts/latest/guide/displaying-data.jade


-  Here's our final code:
+  Here's your final code:


your -> the

I'll be on the lookout for this same opportunity throughout. Done.

kwalrath

One tiny word went missing, but otherwise looks great!

kwalrath · 2016-09-23T17:53:27Z

public/docs/ts/latest/guide/displaying-data.jade

+  The app's code defines the data directly inside the component, which isn't best practice.
+  In a simple demo, however, it's fine.
+
+  At the moment, the binding is !{_an} !{_array} of strings.


is -> is to

googlebot added the CLA: yes label Sep 21, 2016

kwalrath reviewed Sep 21, 2016

View reviewed changes

kwalrath suggested changes Sep 22, 2016

View reviewed changes

kapunahelewong added 2 commits September 23, 2016 10:18

docs(Displaying Data): copy edits

0c44c21

docs(displaying data):copy edits

8c878e7

kapunahelewong force-pushed the kwong-display-data branch from 2eed6f5 to 8c878e7 Compare September 23, 2016 14:18

kwalrath approved these changes Sep 23, 2016

View reviewed changes

docs(displaying data):fix push error and typo

0bd94dd

kapunahelewong force-pushed the kwong-display-data branch from b64eea9 to 0bd94dd Compare September 23, 2016 18:38

kwalrath approved these changes Sep 23, 2016

View reviewed changes

kwalrath merged commit 6c7f330 into angular:master Sep 23, 2016

kwalrath deleted the kwong-display-data branch September 23, 2016 23:53

docs(Displaying Data): copy edits #2435

docs(Displaying Data): copy edits #2435

Uh oh!

Conversation

kapunahelewong commented Sep 21, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath Sep 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath Sep 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath Sep 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath Sep 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwalrath Sep 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

kwalrath Sep 21, 2016 •

edited

Loading

kwalrath Sep 21, 2016 •

edited

Loading

kwalrath Sep 21, 2016 •

edited

Loading

kwalrath Sep 21, 2016 •

edited

Loading

kwalrath Sep 21, 2016 •

edited

Loading