From ce766d9cdd8d57bbe964ce96b08f1e2036947339 Mon Sep 17 00:00:00 2001
From: larsenwork <andreas@larsenwork.com>
Date: Tue, 11 Feb 2020 22:12:31 +0100
Subject: [PATCH] Update documentation on tree-shaking

Related issue: https://github.com/mui-org/material-ui/issues/19549
---
 .../minimizing-bundle-size.md                 | 21 ++++++++++++-------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md b/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
index d5ef2afe536b07..e12883566e716f 100644
--- a/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
+++ b/docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
@@ -9,20 +9,25 @@ on every commit for every package and critical parts of those packages ([view th
 Combined with [dangerJS](https://danger.systems/js/) we can inspect
 [detailed bundle size changes](https://github.com/mui-org/material-ui/pull/14638#issuecomment-466658459) on every Pull Request.
 
-## How to reduce the bundle size?
+## When and how to use tree-shaking?
 
-For convenience, Material-UI exposes its full API on the top-level `material-ui` import.
-If you're using ES6 modules and a bundler that supports tree-shaking ([`webpack` >= 2.x](https://webpack.js.org/guides/tree-shaking/), [`parcel` with a flag](https://en.parceljs.org/cli.html#enable-experimental-scope-hoisting/tree-shaking-support)) you can safely
-use named imports and expect only a minimal set of Material-UI components in your bundle:
+Tree-shaking of Material UI works out of the box in modern frameworks. Material UI exposes its full API on the top-level
+`material-ui` import. If you're using ES6 modules and a bundler that supports tree-shaking
+([`webpack` >= 2.x](https://webpack.js.org/guides/tree-shaking/),
+[`parcel` with a flag](https://en.parceljs.org/cli.html#enable-experimental-scope-hoisting/tree-shaking-support)) you can safely
+use named imports and still get an optimised bundle size automatically:
 
 ```js
 import { Button, TextField } from '@material-ui/core';
 ```
 
-⚠️ Be aware that tree-shaking is an optimization that is usually only applied to production
-bundles. Development bundles will contain the full library which can lead to **slower
-startup times**. This is especially noticeable if you import from `@material-ui/icons`.
-Startup times can be approximately 6x slower than without named imports from the top-level API.
+⚠️ The following instructions are only needed if you want to optimize your development startup times or if you are using an older bundler
+that doesn't support tree-shaking.
+
+## Development environment
+
+Development bundles can contain the full library which can lead to **slower startup times**. This is especially noticeable if you
+import from `@material-ui/icons`. Startup times can be approximately 6x slower than without named imports from the top-level API.
 
 If this is an issue for you, you have various options: