Attempt to add some info about design principles to README
@@ -100,3 +100,74 @@ be as they are released.
This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence
of a Dockerfile will cause all other building behavior to not be triggered.
+
+## Design
+
+`repo2docker` has two primary use cases, which drive most design decisions.
+
+1. Automated image building with projects like
+ [BinderHub](http://github.com/jupyterhub/binderhub)
+2. Manual image building + running using the `jupyter-repo2docker` commandline
+ client on user's interactive workstations.
+
+We enumerate some of these design principles here. This is not an exhaustive
+list :)
+
+### Deterministic output
+
+The core of `repo2docker` can be considered a
+[deterministic algorithm](https://en.wikipedia.org/wiki/Deterministic_algorithm).
+It takes as input a directory which has a repository checked out, and
+deterministically produces a Dockerfile based on the contents of the directory.
+So if we run repo2docker on the the same directory multiple times, we get the
+exact same Dockerfile output.
+
+This provides a few advantages:
+
+1. We can cache the built artifacts based on the identity of the repository we are
+ building. For example, if we had already run repo2docker on a git repository
+ at a particular commit hash, we know we can just re-use the old output, since
+ we know it is going to be the same. This provides massive performance &
+ architectural advantages when building additional tools (like BinderHub) on
+ top of repo2docker.
+2. We produce Dockerfiles that have as much in common as possible across
+ multiple repos, enabling better use of the Docker build cache. This also
+ provides massive performance advantages.
+
+### Unix principles
+
+`repo2docker` should do one thing, and do it well. This one thing is:
+
+> Given a repository (of some sort), deterministically build a docker image from
+> it.
+
+There's also some convenience code (to run the built image) for users, but
+that's separated out cleanly. This allows easy use by other projects (like
+BinderHub).
+
+There is additional (and very useful) design advice on this in
+the [Art of Unix Programming](http://www.faqs.org/docs/artu/ch01s06.html) which
+is a highly recommended quick read.
+
+### Composability
+
+The prime reason `repo2docker` exists (rather than just using something
+like [s2i](https://github.com/openshift/source-to-image)) is we want to support
+*composable* environments. We want to easily have an image with
+Python3+Julia+R-3.2 environments, rather than just one single language
+environment. While generally one language environment per container works well,
+in many scientific / datascience computing environments you need multiple
+languages working together to get anything done. So all buildpacks are
+composable, and need to be able to work well with other languages.
+
+### [Pareto principle](https://en.wikipedia.org/wiki/Pareto_principle)
+
+Roughly speaking, we want to support 80% of use cases, and provide an escape
+hatch (raw Dockerfiles) for the other 20%. We explicitly want to provide support
+only for the most common use cases - covering every possible use case never ends
+well.
+
+An easy process for getting support for more languages here is to demonstrate
+their value with Dockerfiles that other people can use, and then show that this
+pattern is popular enough to be included inside repo2docker. Remember that 'yes'
+is forever (very hard to remove features!), but 'no' is only temporary!
