docs(service-worker): improve service worker guides (angular#43508)

improve slightly the angular.io guides related to service workers, by
means of fixes, styling, information and clarity changes

PR Close angular#43508

Author: dario-piotrowicz

aio/content/examples/service-worker-getting-started/src/app/check-for-update.service.ts

@@ -7,7 +7,8 @@ import { first } from 'rxjs/operators';
 export class CheckForUpdateService {
 
   constructor(appRef: ApplicationRef, updates: SwUpdate) {
-    // Allow the app to stabilize first, before starting polling for updates with `interval()`.
+    // Allow the app to stabilize first, before starting
+    // polling for updates with `interval()`.
     const appIsStable$ = appRef.isStable.pipe(first(isStable => isStable === true));
     const everySixHours$ = interval(6 * 60 * 60 * 1000);
     const everySixHoursOnceAppIsStable$ = concat(appIsStable$, everySixHours$);

aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts

@@ -9,8 +9,10 @@ export class HandleUnrecoverableStateService {
   constructor(updates: SwUpdate) {
     updates.unrecoverable.subscribe(event => {
       notifyUser(
-        `An error occurred that we cannot recover from:\n${event.reason}\n\n` +
-        'Please reload the page.');
+        'An error occurred that we cannot recover from:\n' +
+        event.reason +
+        '\n\nPlease reload the page.'
+      );
     });
   }
 }

aio/content/guide/app-shell.md

@@ -87,4 +87,4 @@ Or to use the production configuration.
 ng run my-app:app-shell:production
 </code-example>
 
-To verify the build output, open `dist/my-app/browser/index.html`. Look for default text `app-shell works!` to show that the application shell route was rendered as part of the output.
+To verify the build output, open <code class="no-auto-link">dist/my-app/browser/index.html</code>. Look for default text `app-shell works!` to show that the application shell route was rendered as part of the output.

aio/content/guide/service-worker-communications.md

@@ -77,7 +77,7 @@ For example, imagine the following scenario:
   This newer version includes the files `index.html`, `main.<main-hash-2>.js` and `lazy-chunk.<lazy-hash-2>.js` (note that the hashes are different now, because the content of the files has changed).
   The old version is no longer available on the server.
 - In the meantime, the user's browser decides to evict `lazy-chunk.<lazy-hash-1>.js` from its cache.
-  Browsers may decide to evict specific (or all) resources from a cache in order to reclaim disk space.
+  This is possible since browsers may decide to evict specific (or all) resources from a cache in order to reclaim disk space.
 - The user opens the application again.
   The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main.<main-hash-1>.js`).
 - At some later point, the application requests the lazy bundle, `lazy-chunk.<lazy-hash-1>.js`.
@@ -87,7 +87,7 @@ For example, imagine the following scenario:
 In the above scenario, the service worker is not able to serve an asset that would normally be cached.
 That particular application version is broken and there is no way to fix the state of the client without reloading the page.
 In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event.
-You can subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors.
+You can subscribe to `SwUpdate.unrecoverable` to be notified and handle these errors.
 
 <code-example path="service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts" header="handle-unrecoverable-state.service.ts" region="sw-unrecoverable-state"></code-example>
 

aio/content/guide/service-worker-config.md

@@ -240,9 +240,9 @@ To use this strategy set `strategy` to `freshness` and `timeout` to `0u` in `cac
 This will essentially do the following:
 
 1. Try to fetch from the network first.
-2. If the network request does not complete after 0ms (that is, immediately), fall back to the cache (ignoring cache age).
-3. Once the network request completes, update the cache for future requests.
-4. If the resource does not exist in the cache, wait for the network request anyway.
+1. If the network request does not complete after 0ms (that is, immediately), fall back to the cache (ignoring cache age).
+1. Once the network request completes, update the cache for future requests.
+1. If the resource does not exist in the cache, wait for the network request anyway.
 
 </div>
 

aio/content/guide/service-worker-devops.md

@@ -23,7 +23,7 @@ This file integrity is especially important when lazy loading modules.
 A JS bundle may reference many lazy chunks, and the filenames of the
 lazy chunks are unique to the particular build of the application. If a running
 application at version `X` attempts to load a lazy chunk, but the server has
-updated to version `X + 1` already, the lazy loading operation will fail.
+already updated to version `X + 1`, the lazy loading operation will fail.
 
 The version identifier of the application is determined by the contents of all
 resources, and it changes if any of them change. In practice, the version
@@ -96,7 +96,7 @@ configured lifetimes.
 
 It can be problematic for an application if the version of resources
 it's receiving changes suddenly or without warning. See the
-[Versions](guide/service-worker-devops#versions) section above
+[App versions](guide/service-worker-devops#versions) section above
 for a description of such issues.
 
 The Angular service worker provides a guarantee: a running application
@@ -303,7 +303,7 @@ Tools open to differ from behavior a user might experience.
 * If you look in the Cache Storage viewer, the cache is frequently
 out of date. Right click the Cache Storage title and refresh the caches.
 
-Stopping and starting the service worker in the Service Worker
+* Stopping and starting the service worker in the Service Worker
 pane triggers a check for updates.
 
 ## Service Worker Safety

aio/content/guide/service-worker-getting-started.md

@@ -10,7 +10,7 @@ A basic understanding of the information in [Introduction to Angular service wor
 
 ## Adding a service worker to your project
 
-To set up the Angular service worker in your project, use the CLI command `ng add @angular/pwa`. It takes care of configuring your application to use service workers by adding the `service-worker` package along
+To set up the Angular service worker in your project, use the CLI command `ng add @angular/pwa`. It takes care of configuring your application to use service workers by adding the `@angular/service-worker` package along
 with setting up the necessary support files.
 
 ```sh
@@ -24,7 +24,7 @@ The above command completes the following actions:
 3. Imports and registers the service worker in the application module.
 4. Updates the `index.html` file:
     * Includes a link to add the `manifest.webmanifest` file.
-    * Adds meta tags for `theme-color`.
+    * Adds a meta tag for `theme-color`.
 5. Installs icon files to support the installed Progressive Web App (PWA).
 6. Creates the service worker configuration file called [`ngsw-config.json`](/guide/service-worker-config), which specifies the caching behaviors and other settings.
 
@@ -55,10 +55,14 @@ http-server -p 8080 -c-1 dist/<project-name>
 
 ### Initial load
 
-With the server running, you can point your browser at http://localhost:8080/. Your application should load normally.
+With the server running, you can point your browser at [http://localhost:8080](http://localhost:8080). Your application should load normally.
+
+<div class="alert is-helpful">
 
 **Tip:** When testing Angular service workers, it's a good idea to use an incognito or private window in your browser to ensure the service worker doesn't end up reading from a previous leftover state, which can cause unexpected behavior.
 
+</div>
+
 <div class="alert is-helpful">
 
 **Note:**
@@ -68,14 +72,16 @@ If you are not using HTTPS, the service worker will only be registered when acce
 
 ### Simulating a network issue
 
-To simulate a network issue, disable network interaction for your application. In Chrome:
+To simulate a network issue, disable network interaction for your application.
+
+In Chrome:
 
 1. Select **Tools** > **Developer Tools** (from the Chrome menu located at the top right corner).
-2. Go to the **Network tab**.
-3. Check the **Offline box**.
+1. Go to the **Network tab**.
+1. Select **Offline** in the **Throttling** dropdown menu.
 
 <div class="lightbox">
-  <img src="generated/images/guide/service-worker/offline-checkbox.png" alt="The offline checkbox in the Network tab is checked">
+  <img src="generated/images/guide/service-worker/offline-option.png" alt="The offline option in the Network tab is selected">
 </div>
 
 Now the application has no access to network interaction.
@@ -90,7 +96,7 @@ If you look at the Network tab, you can verify that the service worker is active
   <img src="generated/images/guide/service-worker/sw-active.png" alt="Requests are marked as from ServiceWorker">
 </div>
 
-Notice that under the "Size" column, the requests state is `(from ServiceWorker)`. This means that the resources are not being loaded from the network. Instead, they are being loaded from the service worker's cache.
+Notice that under the "Size" column, the requests state is `(ServiceWorker)`. This means that the resources are not being loaded from the network. Instead, they are being loaded from the service worker's cache.
 
 
 ### What's being cached?
@@ -104,7 +110,7 @@ Notice that all of the files the browser needs to render this application are ca
 * Images and fonts directly under the configured `outputPath` (by default `./dist/<project-name>/`) or `resourcesOutputPath`. See [`ng build`](cli/build) for more information about these options.
 
 
-<div class="alert is-helpful">
+<div class="alert is-important">
 Pay attention to two key points:
 
 1. The generated `ngsw-config.json` includes a limited list of cacheable fonts and images extensions. In some cases, you might want to modify the glob pattern to suit your needs.
@@ -119,15 +125,15 @@ next step is understanding how updates work. Let's make a change to the applicat
 
 1. If you're testing in an incognito window, open a second blank tab. This will keep the incognito and the cache state alive during your test.
 
-2. Close the application tab, but not the window. This should also close the Developer Tools.
+1. Close the application tab, but not the window. This should also close the Developer Tools.
 
-3. Shut down `http-server`.
+1. Shut down `http-server`.
 
-4. Open `src/app/app.component.html` for editing.
+1. Open `src/app/app.component.html` for editing.
 
-5. Change the text `Welcome to {{title}}!` to `Bienvenue à {{title}}!`.
+1. Change the text `Welcome to {{title}}!` to `Bienvenue à {{title}}!`.
 
-6. Build and run the server again:
+1. Build and run the server again:
 
 ```sh
 ng build
@@ -138,25 +144,26 @@ http-server -p 8080 -c-1 dist/<project-name>
 
 Now look at how the browser and service worker handle the updated application.
 
-1. Open http://localhost:8080 again in the same window. What happens?
+1. Open [http://localhost:8080](http://localhost:8080) again in the same window. What happens?
 
-<div class="lightbox">
-  <img src="generated/images/guide/service-worker/welcome-msg-en.png" alt="It still says Welcome to Service Workers!">
-</div>
+  <div class="lightbox">
+    <img src="generated/images/guide/service-worker/welcome-msg-en.png" alt="It still says Welcome to Service Workers!">
+  </div>
 
-What went wrong? Nothing, actually. The Angular service worker is doing its job and serving the version of the application that it has **installed**, even though there is an update available. In the interest of speed, the service worker doesn't wait to check for updates before it serves the application that it has cached.
+  What went wrong? Nothing, actually. The Angular service worker is doing its job and serving the version of the application that it has **installed**, even though there is an update available. In the interest of speed, the service worker doesn't wait to check for updates before it serves the application that it has cached.
 
-If you look at the `http-server` logs, you can see the service worker requesting `/ngsw.json`. This is how the service worker checks for updates.
+  If you look at the `http-server` logs, you can see the service worker requesting `/ngsw.json`. This is how the service worker checks for updates.
 
-2. Refresh the page.
+1. Refresh the page.
 
-<div class="lightbox">
-  <img src="generated/images/guide/service-worker/welcome-msg-fr.png" alt="The text has changed to say Bienvenue à app!">
-</div>
+  <div class="lightbox">
+    <img src="generated/images/guide/service-worker/welcome-msg-fr.png" alt="The text has changed to say Bienvenue à app!">
+  </div>
 
-The service worker installed the updated version of your application *in the background*, and the next time the page is loaded or reloaded, the service worker switches to the latest version.
+  The service worker installed the updated version of your application *in the background*, and the next time the page is loaded or reloaded, the service worker switches to the latest version.
 
 ## More on Angular service workers
 
 You may also be interested in the following:
+* [App Shell](guide/app-shell).
 * [Communicating with service workers](guide/service-worker-communications).

aio/content/guide/service-worker-intro.md

@@ -17,25 +17,25 @@ Angular applications, as single-page applications, are in a prime position to be
 
 Angular's service worker is designed to optimize the end user experience of using an application over a slow or unreliable network connection, while also minimizing the risks of serving outdated content.
 
-The Angular service worker's behavior follows that design goal:
+To achieve this, the Angular service worker follows these guidelines:
 
 * Caching an application is like installing a native application. The application is cached as one unit, and all files update together.
 * A running application continues to run with the same version of all files. It does not suddenly start receiving cached files from a newer version, which are likely incompatible.
 * When users refresh the application, they see the latest fully cached version. New tabs load the latest cached code.
 * Updates happen in the background, relatively quickly after changes are published. The previous version of the application is served until an update is installed and ready.
 * The service worker conserves bandwidth when possible. Resources are only downloaded if they've changed.
 
-To support these behaviors, the Angular service worker loads a *manifest* file from the server. The manifest describes the resources to cache and includes hashes of every file's contents. When an update to the application is deployed, the contents of the manifest change, informing the service worker that a new version of the application should be downloaded and cached. This manifest is generated from a CLI-generated configuration file called `ngsw-config.json`.
+To support these behaviors, the Angular service worker loads a *manifest* file from the server. The file, called `ngsw.json` (not to be confused with the [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest)), describes the resources to cache and includes hashes of every file's contents. When an update to the application is deployed, the contents of the manifest change, informing the service worker that a new version of the application should be downloaded and cached. This manifest is generated from a CLI-generated configuration file called `ngsw-config.json`.
 
 Installing the Angular service worker is as easy as including an `NgModule`. In addition to registering the Angular service worker with the browser, this also makes a few services available for injection which interact with the service worker and can be used to control it. For example, an application can ask to be notified when a new update becomes available, or an application can ask the service worker to check the server for available updates.
 
 ## Prerequisites
 
-To make use of all the features of Angular service worker, use the latest versions of Angular and the Angular CLI.
+To make use of all the features of Angular service workers, use the latest versions of Angular and the Angular CLI.
 
 In order for service workers to be registered, the application must be accessed over HTTPS, not HTTP.
 Browsers ignore service workers on pages that are served over an insecure connection.
-The reason is that service workers are quite powerful, so extra care needs to be taken to ensure the service worker script has not been tampered with.
+The reason is that service workers are quite powerful, so extra care is needed to ensure the service worker script has not been tampered with.
 
 There is one exception to this rule: to make local development easier, browsers do _not_ require a secure connection when accessing an application on `localhost`.
 
@@ -48,7 +48,7 @@ Browsers like IE and Opera Mini do not support service workers.
 If the user is accessing your application with a browser that does not support service workers, the service worker is not registered and related behavior such as offline cache management and push notifications does not happen.
 More specifically:
 
-* The browser does not download the service worker script and `ngsw.json` manifest file.
+* The browser does not download the service worker script and the `ngsw.json` manifest file.
 * Active attempts to interact with the service worker, such as calling `SwUpdate.checkForUpdate()`, return rejected promises.
 * The observable events of related services, such as `SwUpdate.available`, are not triggered.