add doc for new buildpacks
MODIFY
docs/source/design.md
docs/source/design.md
# Design
-Two primary use cases for `repo2docker` drive most design decisions:
+When designing `repo2docker` and adding to it in the future, the
+developers are influenced by two primary use cases.
+The use cases for `repo2docker` which drive most design decisions are:
1. Automated image building used by projects like
[BinderHub](http://github.com/jupyterhub/binderhub)

ADD
docs/source/dev_newbuildpack.md
+# Adding a new buildpack to repo2docker
+
+A new buildpack is needed when a new language or a new package manager should be
+supported. Buildpacks need to work together. For example, when adding support for
+a new language, like nodejs, the new nodejs buildpack should be able to co-exist
+with Python / R / etc support.
+
+## Criteria to balance and consider
+
+Criteria to balance are:
+
+1. Maintenance burden on repo2docker.
+2. How easy it is to use a given setup without support from repo2docker natively.
+ There are two escape hatches here - `postBuild` and `Dockerfile`.
+3. How widely used is this language / package manager? This is the primary tradeoff
+ with point (1). We (Binder / Jupyter) team do not want to make new formats
+ as much as possible, so ideally we can just say 'X repos on binder already use
+ this using one of the escape hatches in (2), so let us make it easy and add
+ native support'.
+
+## Adding libraries or UI to existing buildpacks
+
+Note that this doesn't apply to adding additional libraries / UI to existing
+buildpacks. For example, if we had an R buildpack and it supported IRKernel,
+it is much easier to
+just support RStudio / Shiny with it, since those are library additions than entirely
+new buildpacks.
\ No newline at end of file

MODIFY
docs/source/index.rst
docs/source/index.rst
@@ -12,6 +12,9 @@ Site Contents
install
usage
- design
faq
samples
+ design
+ architecture
+ dev_newbuildpack
+

add doc for new buildpacks