Merge pull request #1946 from ember-learn/mixonic/modifier-docs

Author: mixonic

guides/release/components/template-lifecycle-dom-and-modifiers.md

@@ -293,10 +293,17 @@ The modifier that we're going to build will allow us to say:
 
 Pretty nice, right?
 
-To accomplish that, we'll create a modifier in `app/modifiers/autofocus.js`. First, install [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) and then generate an `autofocus` modifier for your app:
+New Ember apps ship with a dependency on
+[ember-modifier](https://github.com/ember-modifier/ember-modifier), which
+provides a friendly API for writing your own element modifiers. This library is
+in turn based on a low level API named _modifier managers_. Managers are a
+framework-development level feature, and not something most developers need to
+interact with. You'll see in the following examples that the modifier API is
+imported from the `ember-modifier` package.
+
+First generate the `autofocus` modifier for your application:
 
 ```bash
-ember install ember-modifier
 ember generate modifier autofocus
 ```
 
@@ -308,9 +315,10 @@ import { modifier } from "ember-modifier";
 export default modifier(element => element.focus());
 ```
 
-And that's it!
+And that's it! Now we can use our custom `{{autofocus}}` modifier throughout our application.
 
-Now we can use our custom `{{autofocus}}` modifier throughout our application.
+Read more about the `ember-modifier` APIs at [ember-modifiers:
+Usage](https://github.com/ember-modifier/ember-modifier#usage).
 
 ## Communicating Between Elements in a Component
 
@@ -390,7 +398,6 @@ export default class AudioPlayerComponent extends Component {
 That's it for the component: we're translating the user's interactions into _state_. Now we need to build a modifier to translate the state into the appropriate DOM method calls!
 
 ```bash
-ember install ember-modifier
 ember generate modifier play-when
 ```
 
@@ -448,12 +455,11 @@ document.addEventListener("click", event => {
 
 The most important difference between this example and the cases we've seen so far is that we need to remove the `click` event handler from the document when this element is destroyed.
 
-To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. 
+To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) (which is already installed in newly generated Ember apps) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. 
 
-Run the following commands to install the addon and generate a new modifier:
+Generate the new modifier:
 
 ```bash
-ember install ember-modifier
 ember generate modifier on-click-outside
 ```
 

guides/release/upgrading/current-edition/glimmer-components.md

@@ -784,15 +784,17 @@ functionality that lifecycle hooks contained.
 
 #### Writing your own modifiers
 
-There are also community APIs available for writing your own modifiers, such as
-[ember-modifier](https://github.com/ember-modifier/ember-modifier).
-Ember itself has low level APIs known as _modifier managers_ which can be used
-to write these higher level APIs. In general, it's recommended to use a
-community addon to write modifiers, and _not_ to write your own modifier
-manager.
+New Ember apps ship with a dependency on
+[ember-modifier](https://github.com/ember-modifier/ember-modifier), which
+provides a friendly API for writing your own element modifiers. This library is
+in turn based on a low level API named _modifier managers_. Managers are a
+framework-development level feature, and not something most developers need to
+interact with.
 
-Let's see what our first example would look like if we were to write it as a
-modifier using `ember-modifier`:
+Custom modifiers based on the `ember-modifier` API can be a more expressive
+interface for your logic, and can better encapsulate an implementation.
+
+Let's write a modifier that implements adding an event listener.
 
 ```js {data-filename=app/modifiers/add-event-listener.js}
 import { modifier } from 'ember-modifier';
@@ -825,12 +827,16 @@ export default class ScrollComponent extends Component {
 </div>
 ```
 
-This modifier generalizes the functionality that the component implemented using
-lifecycle hooks before, so we can use this modifier whenever we need to in _any_
-component. This is a much better solution than manually managing event listeners
-every time we need one! At this point, the modifier is effectively the same as
-the `{{on}}` modifier as well, so we could get rid of it altogether and replace
-it with `on`:
+The new `add-event-listener` modifier presents a more expressive interface to
+the `hbs` template: There is only a single modifier to apply instead of two, the
+implementation always tears down after itself upon teardown of the target element,
+and the only JavaScript you have to write during re-user is the implementation
+of the business logic.
+
+At this point, it is worth noting that the custom `{{add-event-listener}}`
+modifier is effectively a re-implementation of the Ember built-in `{{on}}`
+modifier (See the
+[documentation](https://api.emberjs.com/ember/5.1/classes/Ember.Templates.helpers/methods/on?anchor=on)). Using that built-in looks like:
 
 ```handlebars {data-filename=app/components/scroll-component.hbs}
 <div {{on "scroll" this.listener}}>