diff --git a/scripts/package/README.md b/scripts/package/README.md
index 378eb3373fb..58da69ce39e 100644
--- a/scripts/package/README.md
+++ b/scripts/package/README.md
@@ -5,26 +5,10 @@ blocks together to build programs. All code is free and open source.
 
 The source for this module is in the [Blockly repo](http://github.com/google/blockly).
 
-## Installation
-
-You can install this package either via `npm` or `unpkg`.
-
-### npm
-
-```bash
-npm install blockly
-```
-
-### unpkg
-
-```html
-<script src="https://unpkg.com/blockly/blockly.min.js"></script>
-```
-
 ## Example Usage
 
 ```js
-import Blockly from 'blockly';
+import * as Blockly from 'blockly/core';
 Blockly.inject('blocklyDiv', {
     ...
 })
@@ -34,44 +18,71 @@ Blockly.inject('blocklyDiv', {
 
 For samples on how to integrate Blockly into your project, view the list of samples at [blockly-samples](https://github.com/google/blockly-samples).
 
-### Importing Blockly
+## Installation
 
-When you import Blockly with `import * as Blockly from 'blockly';` you'll get the default modules:
-Blockly core, Blockly built-in blocks, the JavaScript generator and the English lang files.
+You can install this package either via `npm` or `unpkg`.
 
-If you need more flexibility, you'll want to define your imports more carefully:
+### unpkg
 
-#### Blockly Core
+```html
+<script src="https://unpkg.com/blockly/blockly.min.js"></script>
+```
+
+When importing from unpkg, you can access imports from the global namespace.
 
 ```js
-import * as Blockly from 'blockly/core';
+// Access Blockly.
+Blockly.thing;
+// Access the default blocks.
+Blockly.Blocks['block_type'];
+// Access the javascript generator.
+javascript.javascriptGenerator;
 ```
 
-#### Blockly built in blocks
+### npm
+
+```bash
+npm install blockly
+```
+
+## Imports
+
+Note: Using import of our package targets requires you to use a bundler (like webpack), since Blockly is packaged as a UMD, rather than an ESM.
 
 ```js
+// Import Blockly core.
+import * as Blockly from 'blockly/core';
+// Import the default blocks.
 import * as libraryBlocks from 'blockly/blocks';
+// Import a generator.
+import {javascriptGenerator} from 'blockly/javascript';
+// Import a message file.
+import * as En from 'blockly/msg/en';
 ```
 
-#### Blockly Generators
-
-If your application needs to generate code from the Blockly blocks, you'll want to include a generator.
+## Requires
 
 ```js
-import {pythonGenerator} from 'blockly/python';
+// Require Blockly core.
+const Blockly = require('blockly/core');
+// Require the default blocks.
+const libraryBlocks = require('blockly/blocks');
+// Require a generator.
+const {javascriptGenerator} = require('blockly/javascript');
+// Require a message file.
+const En = require('blockly/msg/en');
 ```
 
-to include the Python generator. You can also import `{javascriptGenerator} from 'blockly/javascript'`, `{phpGenerator} from 'blockly/php'`, `{dartGenerator} from 'blockly/dart'` and `{luaGenerator} from 'blockly/lua'`.
+## Applying blocks and messages
 
-#### Blockly Languages
+Once you have the library blocks and the message files, you also need to apply
+them.
 
 ```js
-import * as Fr from 'blockly/msg/fr';
-Blockly.setLocale(Fr);
+Blockly.Blocks = libraryBlocks;
+Blockly.setLocal(En);
 ```
 
-To import the French lang files. Once you've imported the specific lang module, you'll also want to set the locale in Blockly.
-
 For a full list of supported Blockly locales, see: [https://github.com/google/blockly/tree/master/msg/js](https://github.com/google/blockly/tree/master/msg/js)
 
 ## License