From 28830aa9050ac25e986080472593e45bf5c47414 Mon Sep 17 00:00:00 2001
From: Peli de Halleux <jhalleux@microsoft.com>
Date: Thu, 19 Jan 2017 17:51:48 -0800
Subject: [PATCH] more info on on-start

---
 docs/blocks.md          | 4 ++++
 docs/blocks/on-start.md | 8 +++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/blocks.md b/docs/blocks.md
index 6b53e456..d0bdba4e 100644
--- a/docs/blocks.md
+++ b/docs/blocks.md
@@ -2,6 +2,10 @@
 
 ### @description Language constructs for the Block editor.
 
+Blocks snap into each other to define the program that your @boardname@ will run.
+Blocks can be event (buttons, shake, ...) or need to be snapped into an event to run. 
+The [on-start](/blocks/on-start) event runs first.
+
 ```namespaces
 for (let i = 0;i<5;++i) {}
 if (true){}
diff --git a/docs/blocks/on-start.md b/docs/blocks/on-start.md
index 723fbf88..65b736cf 100644
--- a/docs/blocks/on-start.md
+++ b/docs/blocks/on-start.md
@@ -16,7 +16,13 @@ input.onButtonPressed(Button.A, () => {
 led.setBrightness(50)
 ```
 
-
 ## What about JavaScript?
 
 ``on-start`` only exists in the block editor. In JavaScript, all code executes sequentially from the first line.
+
+## Hey, my events moved!
+
+When we transform the blocks into JavaScript, we always place all the event registrations (buttons, shake, ...) 
+before launching the ``on start`` code.
+
+If a block from ``on start`` pauses, other registered events will have the opportunity to run as well.
\ No newline at end of file