fix: improve documentation

docs/.vuepress/config.js

@@ -11,7 +11,11 @@ const sidebar = [
   {
     title: 'Developing',
     collapsable: true,
-    children: [['/developing/', 'Getting started'], ['/developing/generator', 'Generators']],
+    children: [
+      ['/developing/', 'Getting started'],
+      '/developing/owc-dev-server',
+      ['/developing/generator', 'Generators'],
+    ],
   },
   {
     title: 'Linting',

docs/building/README.md

@@ -1,20 +1,24 @@
 # Building
 
-A build step is a useful optimization for apps in production. Generally speaking, build steps accomplish some or all of the following:
-1. Code optimization (minification - reducing the size of the app)
-1. Tree shaking (removing dead code)
-1. Bundling (combining modules into single files)
-1. Module resolution (replacing 'bare' module specifiers)
-1. Transforming/polyfilling for older browsers
-1. Supporting non-standard code patterns (e.g. TypeScript or early-stage ECMAScript features)
+## Browser standards
+We strongly believe that staying close to browser standards will be the best long term investment for your code. It is the basis for all our recommendations, and it means that sometimes we will not recommend a popular feature or functionality. It also means we can be faster to adopt and recommend new browser standards.
 
-Our recommendations address the first five points but refrain from introducing non-standard syntaxes and features. We think it's best to avoid those, as they might lock your source code to a specific build setup which can be hard to escape in the future. Javascript is evolving fast, your code can quickly become out of sync with new developments.
+## Building web apps
+Building is a necessary optimization when shipping apps to production. Generally speaking, build tools accomplish some or all of the following:
+1. Code optimization (minification - reducing the size of the app)
+2. Tree shaking (removing dead code)
+3. Bundling and code splitting (combining many files into a few files)
+4. Transforming/polyfilling standard code for older browsers
+5. Transforming/polyfilling experimental standards for older browsers
+6. Transforming/polyfilling non-standard code
+
+Our recommended setups address the first four points but refrain from introducing non-standard features. We think it's best to avoid those, as they might lock your source code to a specific build setup which can be hard to get away from at a later time. Javascript is evolving fast, your code can quickly become out of sync with new developments.
 
 ## Webpack
-[Webpack](https://webpack.js.org/) is a popular and flexible build tool, with a growing ecosystem of plugins. If you're just starting out. we recommend it as a general purpose tool. See [building-webpack](/building/building-webpack.html) to get started.
+[Webpack](https://webpack.js.org/) is a popular and flexible build tool, with a growing ecosystem of plugins. We recommend it as a general purpose tool. See our [default configuration](/building/building-webpack.html) to get started.
 
 ## Rollup
 [Rollup](https://rollupjs.org/) is a another popular build tool which recently had it's 1.0 release. It's especially suitable for optimizing and minifying es modules, and it can output es modules for browsers which have native support. We don't have a recommended setup for rollup yet.
 
 ## Polyfills loader
-We have a web component loader available for use with modern tools. See: ([polyfills-loader](/building/polyfills-loader.html)) for more.
+Web components are not supported yet on Edge and Internet Explorer 11. The recommended approach is to conditionally load the polyfills at runtime using our [Polyfills Loader](/building/polyfills-loader.html) for more.

docs/developing/README.md

@@ -1,11 +1,64 @@
 # Developing
+The web component ecosystem is evolving fast, with many libraries and solutions appearing. High level frameworks such as [Angular](https://angular.io/guide/elements), [Vue](https://github.com/vuejs/vue-web-component-wrapper) and [Stencil](https://stenciljs.com/) provide solutions which compile to web components.
 
-We recommend using the `lit-html` library with the `LitElement` base class for developing web components.
+## Browser standards
+We strongly believe that staying close to browser standards will be the best long term investment for your code. It is the basis for all our recommendations, and it means that sometimes we will not recommend a popular feature or functionality. It also means we can be faster to adopt and recommend new browser standards.
 
-Check out the official documentation for: [lit-html](https://lit-html.polymer-project.org/) and [lit-element](https://lit-element.polymer-project.org/) or check out our code-samples on `Stackblitz`.
+## lit-html
+While there are other good libraries out there, to get started we recommend using the `lit-html` library with the `LitElement` base class for developing web components.
+
+Check out the official documentation for: [lit-html](https://lit-html.polymer-project.org/) and [lit-element](https://lit-element.polymer-project.org/) or check out our code-samples below.
+
+Follow these steps to get started:
+1. Install the required dependencies:
+```
+npm i -D owc-dev-server lit-element
+```
+
+2. Create a `index.html`
+```html
+<!doctype html>
+<html>
+  <head>
+    <script type="module" src="./my-component.js"></script>
+    </head>
+  <body>
+    <my-component></my-component>
+  </body>
+</html>
+```
+
+3. Create a `my-component.js`
+```javascript
+import { LitElement, html } from 'lit-element';
+
+class MyComponent extends LitElement {
+  render() {
+    return html`
+      <p>Hello world!</p>
+    `;
+  }
+}
+
+customElements.define('my-component', MyComponent);
+```
+
+4. Add start scripts to your `package.json`:
+```json
+{
+  "scripts": {
+    "start": "owc-dev-server -o"
+  }
+}
+```
+
+5. Start your app:
+```bash
+npm start
+```
 
 ## Examples
-A collection of live code samples can be found on `Stackblitz`:
+A collection of live code samples for `lit-html` and `LitElement` can be found on `Stackblitz`:
 
 * [Basic](https://open-wc-lit-demos.stackblitz.io/basic)
 	- [01 Basic setup](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F01-basic-setup.js)
@@ -39,5 +92,11 @@ A collection of live code samples can be found on `Stackblitz`:
 	- [07 Template factories](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F07-template-factories.js)
 	- [08 Should update](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F08-should-update.js)
 
+## Browser support
+Not all browsers adopt new features at the same rate. Depending on your browser support requirement, you might end up using features not yet available everywhere. In this case you will need to set up build tools to run your app during development. See `building` below for more.
+
+## Building
+When you are ready to ship your app to production, or when you need to test your app on older browsers, take a look at our [building documentation](/building/) to get you started.
+
 ## Further reading
 See: [awesome lit-html](https://github.com/web-padawan/awesome-lit-html) for a great collection of resources.

docs/developing/owc-dev-server.md

@@ -0,0 +1 @@
+../../packages/owc-dev-server/README.md

packages/building-webpack/README.md

@@ -16,13 +16,13 @@ To set up the default configuration manually:
 
 1. Install the required dependencies:
 ```bash
-npm i -D @open-wc/webpack webpack webpack-dev-server http-server
+npm i -D @open-wc/building-webpack webpack webpack-dev-server http-server
 ```
 
 2. Create a file `webpack.config.js`:
 ```javascript
 const path = require('path');
-const defaultConfig = require('@open-wc/webpack/default-config');
+const defaultConfig = require('@open-wc/building-webpack/default-config');
 
 module.exports = defaultConfig();
 ```
@@ -98,8 +98,8 @@ By default, babel's compilation of async functions and `for of` loops using an e
 
 For async functions we use the [fast-async](https://github.com/MatAtBread/fast-async) plugin instead.
 
-### Polyfills by usage
-[Language polyfills](https://github.com/zloirock/core-js) are added based on browser support and usage. This leads to a significantly smaller initial bundle of your app.
+### es2015 polyfills
+We add [Language polyfills](https://github.com/zloirock/core-js) for `es2015` features, such as `Map` and `'/foo'.startsWith('/')`. But only on the `es5` build, so that we don't need to ship it to modern browsers.
 
 ### Syntax and javascript APIs
 Our config only supports standard javascript syntax and browser APIs. We support stage 3 proposals when they add significant value and are easy to support without performance penalties.
@@ -114,7 +114,7 @@ The `default-config` function outputs a regular webpack config, it can easily be
 ```javascript
 const path = require('path');
 const merge = require('webpack-merge');
-const createDefaultConfig = require('@open-wc/webpack/default-config');
+const createDefaultConfig = require('@open-wc/building-webpack/default-config');
 
 const defaultConfig = createDefaultConfig();
 

packages/owc-dev-server/README.md

@@ -20,7 +20,19 @@ becomes:
 ```javascript
 import { html } from '../../node_modules/lit-html/lit-html.js';
 ```
-This will become obsolete over time, as a similar behavior is being standardized in browsers: https://github.com/WICG/import-maps
+This will become obsolete over time, as a similar behavior is being standardized in browsers. It's called [import maps](https://github.com/WICG/import-maps).
+
+Note: import paths are only resolved within `.js` files. This means you cannot do a bare module import from your `index.html`:
+```html
+<html>
+  <head>
+    <script type="module">
+      import { html } from 'lit-html'; // does not work
+    </script>
+  </head>
+  <body></body>
+</html>
+```
 
 ### Usage
 ```bash