diff --git a/doc/component.md b/doc/component.md
index 763dcf60..cbc6ad5f 100644
--- a/doc/component.md
+++ b/doc/component.md
@@ -1,3 +1,30 @@
 # Component
 
-hey
+Components are the reusable, composable widgets. They are designed to be low
+level, to be declarative, and with asynchronous rendering.
+
+For example:
+
+```javascript
+export class Counter extends Component {
+  inlineTemplate = `
+    <div t-name="counter">
+      <button t-on-click="increment(-1)">-</button>
+      <span style="font-weight:bold">Value: <t t-esc="state.counter"/></span>
+      <button t-on-click="increment(1)">+</button>
+    </div>`;
+
+  state = {
+    counter: 0
+  };
+
+  constructor(parent, props) {
+    super(parent, props);
+    this.state.counter = props.initialState || 0;
+  }
+
+  increment(delta) {
+    this.updateState({ counter: this.state.counter + delta });
+  }
+}
+```
diff --git a/doc/qweb.md b/doc/qweb.md
index b7c29ee8..7ee88951 100644
--- a/doc/qweb.md
+++ b/doc/qweb.md
@@ -1,3 +1,27 @@
 # QWeb
 
-hey
+QWeb is a template specification. The QWeb class in this repository is:
+
+- an implementation of the QWeb specification
+- which outputs a virtual dom instead of a string
+- and extended with a few extra directives
+
+## QWeb Specification
+
+add here a full description of what QWeb is supposed to be, with some examples
+
+## QWeb Implementation
+
+```javascript
+var qweb = new QWeb();
+qweb.addTemplate("sometemplate", '<div>hello <t t-esc="name"/></div>');
+
+// result is a vnode which represent <div>hello world</div>
+result = qweb.render("sometemplate", { name: "world" });
+```
+
+## QWeb extensions
+
+- t-on directive
+- t-widget, t-props, t-key
+- t-ref