diff --git a/README.md b/README.md
index 061165f7..cd266652 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,20 @@ If you are hosting your `.js` on a different domain (e.g. on a CDN) than the HTM
 -->
 ```
 
+## Documentation
+
+Please program against the API described in `monaco.d.ts`.
+
+See the editor in action [here](https://microsoft.github.io/monaco-editor/index.html).
+
+Find full HTML samples [here](https://github.com/Microsoft/monaco-editor-samples).
+
+Explore API samples [here](https://microsoft.github.io/monaco-editor/playground.html).
+![image](https://cloud.githubusercontent.com/assets/5047891/16143056/9909d2d6-346a-11e6-86dc-f4f75c94ed2b.png)
+
+Create a Monarch tokenizer [here](https://microsoft.github.io/monaco-editor/monarch.html).
+![image](https://cloud.githubusercontent.com/assets/5047891/16143041/840ced64-346a-11e6-98f3-3c68bf61884a.png)
+
 ## FAQ
 
 > Q: What is the relationship between VS Code and the Monaco Editor?<br/>