diff --git a/README.md b/README.md
index 80e7639c..4114793d 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,16 @@
 
 ## Project Overview
 
-Odoo Web Library (OWL) is a project to collect some useful, reusable, (hopefully)
-well designed building blocks for building web applications. However, since this is the basis for the Odoo web client, we will not hesitate
-to design the code here to better match the Odoo architecture/design principles.
+The Odoo Web Library (OWL) is a small (currently around 11k minified and gzipped)
+framework intended to be the basis for the Odoo Web Client, and hopefully many
+other Odoo related projects.
 
-The most important element of this repository is certainly the component system.
-It is designed to be:
+Briefly, the OWL framework contains:
+
+- a declarative component system, with a virtual dom based on a fork of Snabbdom
+- and a store (state management solution, loosely inspired by VueX and React/Redux)
+
+The component system is designed to be:
 
 1. **declarative:** the user interface should be described in term of the state
    of the application, not as a sequence of imperative steps.
@@ -22,12 +26,6 @@ It is designed to be:
 4. **uses QWeb as a template system:** the templates are described in XML
    and follow the QWeb specification. This is a requirement for Odoo.
 
-5. **with an imperative escape hatch:** if necessary, sub widgets can easily be
-   manually created/destroyed.
-
-Note: the code is written in typescript. This does not mean that the main web
-client will ever be converted to typescript (even though I would really like it).
-
 ## Try it online
 
 You can experiment with the OWL project online: [https://odoo.github.io/owl/](https://odoo.github.io/owl/)
@@ -47,6 +45,7 @@ Some npm scripts are available:
 
 ## Documentation
 
+
 The complete documentation can be found [here](doc/readme.md). The most important sections are:
 
 - [Quick Start](doc/quick_start.md)
@@ -71,38 +70,33 @@ const hello = new HelloWorld(env, { name: "World" });
 hello.mount(document.body);
 ```
 
-The next example show how interactive widgets can be created and how widget
+The next example show interactive widgets, and how widget
 composition works:
 
 ```javascript
-class Counter extends owl.core.Component {
+class ClickCounter extends owl.core.Component {
   inlineTemplate = `
     <div>
-      <button t-on-click="increment(-1)">-</button>
-      <span style="font-weight:bold">Value: <t t-esc="state.value"/></span>
-      <button t-on-click="increment(1)">+</button>
+      <button t-on-click="increment">Click Me! [<t t-esc="state.value"/>]</button>
     </div>`;
 
   constructor(parent, props) {
     super(parent, props);
-    this.state = {
-      value: props.initialState || 0
-    };
+    this.state = { value: 0 };
   }
 
-  increment(delta) {
-    this.updateState({ value: this.state.value + delta });
+  increment() {
+    this.state.value++;
   }
 }
 
 class App extends owl.core.Component {
   inlineTemplate = `
     <div>
-        <t t-widget="Counter" t-props="{initialState: 1}"/>
-        <t t-widget="Counter" t-props="{initialState: 42}"/>
+        <t t-widget="ClickCounter"/>
     </div>`;
 
-  widgets = { Counter };
+  widgets = { ClickCounter };
 }
 
 const env = {
@@ -113,11 +107,7 @@ const app = new App(env);
 app.mount(document.body);
 ```
 
-More interesting examples on how to work with this web framework can be found in the _examples/_ folder:
-
-- [Todo Application](examples/readme.md#todo-app)
-- [Web Client](examples/readme.md#web-client-example)
-- [Benchmarks](examples/readme.md#benchmarks)
+More interesting examples can be found on the playground application: [https://odoo.github.io/owl/](https://odoo.github.io/owl/).
 
 ## License