Glossary copy edit #25468

jbogarthyde · 2018-08-13T21:44:00Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] angular.io application / infrastructure changes
[ ] Other... Please describe:

What is the current behavior?

Issue Number: N/A

What is the new behavior?

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

mary-poppins · 2018-08-14T22:20:17Z

You can preview 636f214 at https://pr25468-636f214.ngbuilds.io/.

jbogarthyde · 2018-08-14T23:18:32Z

@jenniferfell All green now except approvals

mary-poppins · 2018-08-15T15:42:43Z

You can preview 5a4b921 at https://pr25468-5a4b921.ngbuilds.io/.

mary-poppins · 2018-08-16T16:44:33Z

You can preview e96757b at https://pr25468-e96757b.ngbuilds.io/.

jbogarthyde · 2018-08-16T18:43:39Z

@jenniferfell All green now except approvals

jenniferfell

Some things to fix before releasing:

Line breaks in some unexpected places (not paragraph breaks)
Inconsistent vert spacing in lists
A few caps or other copy edit things

Optional:

Some places where a comma was included out of habit but is not correct or where a comma is standing in for missing words.
Some places where a "which" or "that" clause could be more clear.
Optional because I'm not sure if we can be more clear in this copy edit pass. Might need to put on backlog to rewrite some definitions.

jenniferfell · 2018-08-16T17:32:23Z

aio/content/guide/glossary.md



-A function that modifies the immediately following class or property definition.  
-Decorators (also called annotations) are an experimental (stage 2), JavaScript language [feature](https://github.com/wycats/javascript-decorators). 
+A function that modifies a class or property definition.  


For some reason, there is a line break (but not a paragraph break) at the end of this sentence in the output.

jenniferfell · 2018-08-16T17:32:55Z

aio/content/guide/glossary.md

-A function that modifies the immediately following class or property definition.  
-Decorators (also called annotations) are an experimental (stage 2), JavaScript language [feature](https://github.com/wycats/javascript-decorators). 
+A function that modifies a class or property definition.  
+Decorators (also called *annotations*) are an experimental (stage 2), JavaScript language [feature](https://github.com/wycats/javascript-decorators). 


Remove , after (stage 2)

jenniferfell · 2018-08-16T17:35:07Z

aio/content/guide/glossary.md


-## Domain-specific language (DSL)
+## domain-specific language (DSL)

 A special-purpose library or API; see [Domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language).

 Angular extends TypeScript with domain-specific languages for a number of domains relevant to Angular apps, defined in ngModules such as [animations](guide/animations), [forms](guide/forms), and [routing and navigation](guide/router).


Capitalize NgModules

jenniferfell · 2018-08-16T17:43:10Z

aio/content/guide/glossary.md


-Both a [service](guide/glossary#service) and a [component](guide/glossary#component) that depends on that service must be marked as injectable. Other items, such as constant values, can be injectable.
+Both [services](guide/glossary#service) and [components](guide/glossary#component) that depends on those service must be marked as injectables. Other items, such as constant values, can be injectable.


Both services and components that depend ...

jenniferfell · 2018-08-16T20:07:26Z

aio/content/guide/glossary.md

-## Directive
-
-A class with the `@Directive` [decorator](guide/glossary#decorator) that can modify the structure of the DOM, or modify attributes in the DOM and component data model.
+A class with the `@Directive()` [decorator](guide/glossary#decorator) that can modify the structure of the DOM, or modify attributes in the DOM and component data model.

 A directive class is usually associated with an HTML element or attribute, and that element or attribute is often referred to as the directive itself.  


For some reason, in the output there is a line break (but not a paragraph break) at the end of the first sentence.

jenniferfell · 2018-08-16T21:26:15Z

aio/content/guide/glossary.md


-In Angular, a [project](guide/glossary#project) that provides functionality that can be included in other Angular apps. A library is not a complete Angular app, and it cannot run independently. 
+In Angular, a [project](guide/glossary#project) that provides functionality that can be included in other Angular apps. 
+A library isn't a complete Angular app, and can't run independently. 


Extra comma:

A library isn't a complete Angular app and can't run independently.

jenniferfell · 2018-08-16T21:51:30Z

aio/content/guide/glossary.md

-## Module
+{@a module}
+
+## module

 In general, a module collects a block of code dedicated to a single purpose. Angular uses standard JavaScript modules, and also defines an Angular module, `NgModule`. 


Global. The existing docs have a lot of sentences that technically have a compound predicate with a comma. While the comma is allowed in some cases for clarity, a compound predicate typically should not have a comma. This extra comma is often a clue that the sentence has other problems. Either there is simply an extra comma out of (bad) habit, or the sentence would benefit from more words or smaller bites.

Incorrect: I ate pizza, and also ate ice cream.
Correct: I ate pizza and also ate ice cream.
Correct: I ate pizza, and I also ate ice cream.
Better: I ate pizza and ice cream.

Current: Angular uses standard JavaScript modules, and also defines an Angular module, NgModule.

1 Drop the comma: Angular uses standard JavaScript modules and also defines an Angular module, NgModule.

2 Compound sentence: Angular uses standard JavaScript modules, and it also defines an Angular module, NgModule.

3 Two sentences: Angular uses standard JavaScript modules. It also defines an Angular-specific module, NgModule.

I think 1 gets the job done here.

jenniferfell · 2018-08-16T21:52:55Z

aio/content/guide/glossary.md


 In general, a module collects a block of code dedicated to a single purpose. Angular uses standard JavaScript modules, and also defines an Angular module, `NgModule`. 

 In JavaScript (ECMAScript), each file is a module and all objects defined in the file belong to that module. Objects can exported, making them public, and public objects can be imported for use by other modules.

-Angular ships as a collection of JavaScript modules, or libraries. Each Angular library name begins with the `@angular` prefix. Install them with the npm package manager and import parts of them with JavaScript `import` declarations.
+Angular ships as a collection of JavaScript modules, or libraries. Each Angular library name begins with the `@angular` prefix. Install them with the `npm` package manager and import parts of them with JavaScript `import` declarations.


"them" doesn't have a direct referent
Recommend: Install Angular libraries with the...

jenniferfell · 2018-08-16T21:54:48Z

aio/content/guide/glossary.md


-## Bootstrap
+## bootstrap

 A way to initialize and launch an app or system.

 In Angular, an app's root NgModule (`AppModule`) has a `bootstrap` property that identifies the app's top-level [components](guide/glossary#component). 
 During the bootstrap process, Angular creates and inserts these components into the `index.html` host web page. 
 You can bootstrap multiple apps in the same `index.html`, each app with its own components.


I feel like a word is missing in this sentence

jenniferfell · 2018-08-16T22:52:19Z

aio/content/guide/glossary.md


 In general, a module collects a block of code dedicated to a single purpose. Angular uses standard JavaScript modules, and also defines an Angular module, `NgModule`. 

 In JavaScript (ECMAScript), each file is a module and all objects defined in the file belong to that module. Objects can exported, making them public, and public objects can be imported for use by other modules.

-Angular ships as a collection of JavaScript modules, or libraries. Each Angular library name begins with the `@angular` prefix. Install them with the npm package manager and import parts of them with JavaScript `import` declarations.
+Angular ships as a collection of JavaScript modules, or libraries. Each Angular library name begins with the `@angular` prefix. Install them with the `npm` package manager and import parts of them with JavaScript `import` declarations.


Another comma standing in for words. Grammatically fine as is, but if we can be more clear without too much effort, that would be great.

Angular ships as a collection of JavaScript modules (also called libraries).

Angular ships as a collection of JavaScript modules or libraries. [diff things]

jenniferfell · 2018-08-16T23:06:23Z

P.S. Please squash commits. Thanks!

mary-poppins · 2018-08-17T15:32:32Z

You can preview bc20c68 at https://pr25468-bc20c68.ngbuilds.io/.

mary-poppins · 2018-08-17T15:42:22Z

You can preview 580b5bc at https://pr25468-580b5bc.ngbuilds.io/.

mary-poppins · 2018-08-17T19:03:49Z

You can preview f1b6f55 at https://pr25468-f1b6f55.ngbuilds.io/.

PR Close #25468

PR Close angular#25468

angular-automatic-lock-bot · 2019-09-13T23:24:10Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

jbogarthyde added comp: docs target: patch This PR is targeted for the next patch release labels Aug 13, 2018

googlebot added the cla: yes label Aug 13, 2018

jbogarthyde force-pushed the jb-glossary-edit branch from 4a5fcb1 to cc44868 Compare August 14, 2018 22:04

jbogarthyde force-pushed the jb-glossary-edit branch from 636f214 to 5a4b921 Compare August 15, 2018 15:31

jbogarthyde force-pushed the jb-glossary-edit branch from 5a4b921 to e96757b Compare August 16, 2018 16:27

jbogarthyde requested a review from jenniferfell August 16, 2018 16:29

jenniferfell approved these changes Aug 16, 2018

View reviewed changes

jbogarthyde force-pushed the jb-glossary-edit branch 4 times, most recently from 75def40 to bc20c68 Compare August 17, 2018 15:24

jbogarthyde force-pushed the jb-glossary-edit branch from bc20c68 to 580b5bc Compare August 17, 2018 15:35

docs: copy edit glossary

f1b6f55

jbogarthyde force-pushed the jb-glossary-edit branch from 580b5bc to f1b6f55 Compare August 17, 2018 18:56

jbogarthyde added the action: merge The PR is ready for merge by the caretaker label Aug 17, 2018

jasonaden closed this in d2be3d5 Aug 17, 2018

jasonaden pushed a commit that referenced this pull request Aug 17, 2018

docs: copy edit glossary (#25468)

5939c42

PR Close #25468

jbogarthyde deleted the jb-glossary-edit branch August 20, 2018 16:51

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

docs: copy edit glossary (angular#25468)

ed505e7

PR Close angular#25468

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Glossary copy edit #25468

Glossary copy edit #25468

jbogarthyde commented Aug 13, 2018 •

edited

Loading

mary-poppins commented Aug 14, 2018

jbogarthyde commented Aug 14, 2018

mary-poppins commented Aug 15, 2018

mary-poppins commented Aug 16, 2018

jbogarthyde commented Aug 16, 2018

jenniferfell left a comment

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell Aug 16, 2018

jenniferfell commented Aug 16, 2018

mary-poppins commented Aug 17, 2018

mary-poppins commented Aug 17, 2018

mary-poppins commented Aug 17, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019


		Both a [service](guide/glossary#service) and a [component](guide/glossary#component) that depends on that service must be marked as injectable. Other items, such as constant values, can be injectable.
		Both [services](guide/glossary#service) and [components](guide/glossary#component) that depends on those service must be marked as injectables. Other items, such as constant values, can be injectable.

Glossary copy edit #25468

Glossary copy edit #25468

Conversation

jbogarthyde commented Aug 13, 2018 • edited Loading

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

mary-poppins commented Aug 14, 2018

jbogarthyde commented Aug 14, 2018

mary-poppins commented Aug 15, 2018

mary-poppins commented Aug 16, 2018

jbogarthyde commented Aug 16, 2018

jenniferfell left a 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

jenniferfell commented Aug 16, 2018

mary-poppins commented Aug 17, 2018

mary-poppins commented Aug 17, 2018

mary-poppins commented Aug 17, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019

jbogarthyde commented Aug 13, 2018 •

edited

Loading