[DOC] *: improve some parts of the doc

doc/readme.md

@@ -3,16 +3,20 @@
 
 ## Reference
 
+- [Animations](animations.md)
 - [Component](component.md)
+- [Event Bus](event_bus.md)
+- [Observer](observer.md)
 - [QWeb](qweb.md)
 - [Store](store.md)
-- [Observer](observer.md)
-- [Event Bus](event_bus.md)
-- [Virtual DOM](vdom.md)
 - [Utils](utils.md)
+- [Virtual DOM](vdom.md)
+
+## Learning resources
+
+- [Quick Start](quick_start.md)
 
 ## Miscellaneous
-- [Quick Start](quick_start.md)
-- [Animations](animations.md)
-- [Tooling](tooling.md)
+
 - [Comparison with React/Vue](comparison.md)
+- [Tooling](tooling.md)

doc/utils.md

@@ -5,11 +5,11 @@ functions are all available in the `owl.utils` namespace.
 
 ## Content
 
-- [`whenReady`](#whenready)
-- [`loadJS`](#loadjs)
-- [`loadTemplates`](#loadtemplates)
-- [`escape`](#escape)
-- [`debounce`](#debounce)
+- [`whenReady`](#whenready): executing code when DOM is ready
+- [`loadJS`](#loadjs): loading script files
+- [`loadTemplates`](#loadtemplates): loading xml files
+- [`escape`](#escape): sanitizing strings
+- [`debounce`](#debounce): limiting rate of function calls
 
 ## `whenReady`
 
@@ -17,23 +17,40 @@ The function `whenReady` is useful to register some code that need to be execute
 as soon as the document (page) is ready:
 
 ```js
-owl.utils.whenReady(function () {
-    const qweb = new owl.QWeb();
-    const app = new App({ qweb });
-    app.mount(document.body);
+owl.utils.whenReady(function() {
+  const qweb = new owl.QWeb();
+  const app = new App({ qweb });
+  app.mount(document.body);
 });
 ```
 
+
 ## `loadJS`
 
+`loadJS` takes a url (string) for a javascript resource, and loads it. It returns
+a promise, so the caller can properly react when it is ready.  Also, it is smart:
+it maintains a list of urls previously loaded (or currently being loaded), and
+prevent doing twice the work.
+
+```js
+class MyComponent extends owl.Component {
+    willStart() {
+        return owl.utils.loadJS('/static/libs/someLib.js');
+    }
+}
+```
+
 ## `loadTemplates`
 
+```js
+async function makeEnv() {
+    const templates = await owl.utils.loadTemplates('templates.xml');
+    const qweb = new owl.QWeb(templates);
+    return { qweb };
+}
+```
+
 ## `escape`
 
+
 ## `debounce`
-
-
-
-
-
-

doc/vdom.md

@@ -1,3 +1,21 @@
 # 🦉 VDom 🦉
 
-Owl's virtual dom is a fork of [snabbdom](https://github.com/snabbdom/snabbdom).
+Owl is a declarative component system: we declare the structure of the component
+tree, and Owl will translate that to a list of imperative operations.  This
+translation is done by a virtual dom. This is the low level layer of Owl, most
+developer will not need to call directly the virtual dom functions.
+
+
+The main idea behind a virtual dom is to keep a in-memory representation of the
+DOM (called a virtual node), and whenever some change is needed, to regenerate
+a new representation, compute the difference between the old and the new, then
+apply the changes.
+
+`vdom` exports two functions:
+
+- `h`: create a new virtual node
+- `patch`: compare two virtual nodes, and apply the difference.
+
+Note: Owl's virtual dom is a fork of [snabbdom](https://github.com/snabbdom/snabbdom).
+
+