diff --git a/README.md b/README.md
new file mode 100644
index 0000000..45a395f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+# Magnum + Qt Quick bootstrap
+
+This app demonstrates usage if Magnum rendering engine within a Qt Quick application.
+
+## Common pitfalls
+
+### Header inclusion order
+
+Follow a simple rules: Always include Magnum's headers first. If you're including
+your own headers, make sure that this rules is preserved. It's very easy to violate it.
+
+Common symptom is compiler errors about missing declarations for `glFinish`, `glFlush`
+and `glGetError`, which some Qt headers (`QOpenGLFunctions`) are unbdefining.
+
+For a bomb-proof solution, make a header file that includes all of your Magnum and Qt
+dependencies in correct order.
+
+### CMake AUTOMOC
+
+CMake detects a Qt project and enables `moc` preprocessor automatically for certain
+source files. This may not play well with Magnum's headers. If you see `moc` related
+build errors in Magnum's headers, improve separation between Magnum and Qt code, ie.
+move Magnum code to its own source files.