From be545bd0ade7fbd750b1f522533c0b3ddee98aec Mon Sep 17 00:00:00 2001
From: yuvipanda <yuvipanda@gmail.com>
Date: Tue, 24 Oct 2017 14:02:54 -0700
Subject: [PATCH] Add a basic FAQ doc + 1 entry

We get lots of questions that can be answered here!
---
 docs/source/faq.md    | 19 +++++++++++++++++++
 docs/source/index.rst |  1 +
 2 files changed, 20 insertions(+)
 create mode 100644 docs/source/faq.md

diff --git a/docs/source/faq.md b/docs/source/faq.md
new file mode 100644
index 00000000..7b8d8232
--- /dev/null
+++ b/docs/source/faq.md
@@ -0,0 +1,19 @@
+# Frequently Asked Questions (FAQ)
+
+A collection of frequently asked questions with answers!
+
+If you have a question & have found an answer, send a PR to add it here!
+
+## Can I use repo2docker to bootstrap my own Dockerfile?
+
+If you pass the `--debug` flag to `repo2docker`, it outputs the intermediate
+Dockerfile it is using to build the docker image. While it is tempting to copy
+this as a base for your own Dockerfile, that is not supported & in most cases
+will not work. The `--debug` output is just our intermediate generated
+Dockerfile, and is meant to be built in
+[a very specific way](https://github.com/jupyter/repo2docker/blob/master/repo2docker/detectors.py#L381).
+Hence the output of `--debug` can not be built with a normal `docker build -t .`
+or similar traditional docker command.
+
+Check out the [binder-examples](http://github.com/binder-examples/) github
+organization for example Dockerfiles you can copy & modify for your own use!
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9a9cb625..93f0bb99 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -11,4 +11,5 @@ Site Contents
    :maxdepth: 2
 
    design
+   faq
    samples