Tweak user guide a bit

Author: gaearon

packages/react-scripts/template/README.md

@@ -24,8 +24,8 @@ You can find the most recent version of this guide [here](https://github.com/fac
 - [Importing a Component](#importing-a-component)
 - [Code Splitting](#code-splitting)
 - [Adding a Stylesheet](#adding-a-stylesheet)
-- [Adding a CSS Modules stylesheet](#adding-a-css-modules-stylesheet)
-- [Adding a Sass stylesheet](#adding-a-sass-stylesheet)
+- [Adding a CSS Modules Stylesheet](#adding-a-css-modules-stylesheet)
+- [Adding a Sass Stylesheet](#adding-a-sass-stylesheet)
 - [Post-Processing CSS](#post-processing-css)
 - [Adding Images, Fonts, and Files](#adding-images-fonts-and-files)
 - [Adding SVGs](#adding-svgs)
@@ -511,15 +511,15 @@ In development, expressing dependencies this way allows your styles to be reload
 
 If you are concerned about using Webpack-specific semantics, you can put all your CSS right into `src/index.css`. It would still be imported from `src/index.js`, but you could always remove that import if you later migrate to a different build tool.
 
-## Adding a CSS Modules stylesheet
+## Adding a CSS Modules Stylesheet
 
 > Note: this feature is available with `react-scripts@2.0.0` and higher.
 
-This project supports [CSS Modules](https://github.com/css-modules/css-modules) alongside regular stylesheets using the **[name].module.css** file naming convention. CSS Modules allows the scoping of CSS by automatically creating a unique classname of the format **[filename]\_[classname]\_\_[hash]**.
+This project supports [CSS Modules](https://github.com/css-modules/css-modules) alongside regular stylesheets using the `[name].module.css` file naming convention. CSS Modules allows the scoping of CSS by automatically creating a unique classname of the format `[filename]\_[classname]\_\_[hash]`.
 
-> **Tip:** Should you want to preprocess a stylesheet with Sass then make sure to [follow the installation instructions](#adding-a-sass-stylesheet) and then change the stylesheet file extension as follows: _[name].module.scss_ or _[name].module.sass_.
+> **Tip:** Should you want to preprocess a stylesheet with Sass then make sure to [follow the installation instructions](#adding-a-sass-stylesheet) and then change the stylesheet file extension as follows: `[name].module.scss` or `[name].module.sass`.
 
-An advantage of this is the ability to repeat the same classname within many CSS files without worrying about a clash.
+CSS Modules let you use the same CSS class name in different files without worrying about naming clashes. Learn more about CSS Modules [here](https://css-tricks.com/css-modules-part-1-need/).
 
 ### `Button.module.css`
 
@@ -552,7 +552,7 @@ class Button extends Component {
 }
 ```
 
-### `exported HTML`
+### Result
 
 No clashes from other `.error` class names
 
@@ -561,9 +561,9 @@ No clashes from other `.error` class names
 <button class="Button_error_ax7yz"></div>
 ```
 
-**This is an optional feature.** Regular html stylesheets and js imported stylesheets are fully supported. CSS Modules are only added when explicitly named as a css module stylesheet using the extension `.module.css`.
+**This is an optional feature.** Regular `<link>` stylesheets and CSS files are fully supported. CSS Modules are turned on for files ending with the `.module.css` extension.
 
-## Adding a Sass stylesheet
+## Adding a Sass Stylesheet
 
 > Note: this feature is available with `react-scripts@2.0.0` and higher.
 
@@ -685,8 +685,7 @@ One way to add SVG files was described in the section above. You can also import
 
 ```js
 import { ReactComponent as Logo } from './logo.svg'
-
-const App = () => (
+ const App = () => (
   <div>
     {/* Logo is an actual React component */}
     <Logo />
@@ -1018,12 +1017,11 @@ REACT_APP_BAR=$DOMAIN/bar
 
 ## Can I Use Decorators?
 
-Many popular libraries use [decorators](https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841) in their documentation.<br>
-Create React App doesn’t support decorator syntax at the moment because:
+Some popular libraries use [decorators](https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841) in their documentation.<br>
+Create React App intentionally doesn’t support decorator syntax at the moment because:
 
-- It is an experimental proposal and is subject to change.
-- The current specification version is not officially supported by Babel.
-- If the specification changes, we won’t be able to write a codemod because we don’t use them internally at Facebook.
+- It is an experimental proposal and is subject to change (in fact, it has already changed once, and will change again).
+- Most libraries currently support only the old version of the proposal — which will never be a standard.
 
 However in many cases you can rewrite decorator-based code without decorators just as fine.<br>
 Please refer to these two threads for reference:
@@ -1715,6 +1713,7 @@ Learn more about React Storybook:
 - [GitHub Repo](https://github.com/storybooks/storybook)
 - [Snapshot Testing UI](https://github.com/storybooks/storybook/tree/master/addons/storyshots) with Storybook + addon/storyshot
 
+<!--
 ### Getting Started with Styleguidist
 
 Styleguidist combines a style guide, where all your components are presented on a single page with their props documentation and usage examples, with an environment for developing components in isolation, similar to Storybook. In Styleguidist you write examples in Markdown, where each code snippet is rendered as a live editable playground.
@@ -1786,6 +1785,8 @@ Offline-first Progressive Web Apps are faster and more reliable than traditional
 - Your app will work regardless of network state, even if offline. This means your users will be able to use your app at 10,000 feet and on the subway.
 - On mobile devices, your app can be added directly to the user's home screen, app icon and all. This eliminates the need for the app store.
 
+However, they [can make debugging deployments more challenging](https://github.com/facebook/create-react-app/issues/2398) so, starting with Create React App 2, service workers are opt-in.
+
 The [`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin)
 is integrated into production configuration,
 and it will take care of generating a service worker file that will automatically