diff --git a/docs/codebase/design-philosophy.md b/docs/codebase/design-philosophy.md
new file mode 100644
index 00000000..a5785752
--- /dev/null
+++ b/docs/codebase/design-philosophy.md
@@ -0,0 +1,9 @@
+Kaleidoscope should, in order:  
+
+1) Work well as a keyboard 
+2) Be compatible with real hardware 
+3) Be compatible with the spec 
+4) Be easy to read and understand 
+5) Be easy to modify and customize
+
+Our code indentation style is managed with 'make astyle.' For code we 'own', there should be an astyle target in the Makefile. For third party code we use and expect to update (ever), we try not to mess with the upstream house style.
diff --git a/docs/index.rst b/docs/index.rst
index 8192582b..b51137b1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -51,7 +51,8 @@ Understanding the codebase
 
 .. toctree::
    :maxdepth: 1
-
+  
+   codebase/design-philosophy.md
    codebase/glossary.md
    codebase/code-style.md