added faq
diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..45cb70e
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,37 @@
+Frequently asked questions
+##########################
+
+(under construction)
+
+Limitations involving reference arguments
+=========================================
+
+In C++, it's fairly common to pass arguments using mutable references or
+mutable pointers, which allows both read and write access to the value
+supplied by the caller. This is sometimes done for efficiency reasons, or to
+realize functions that have multiple return values. Here are two very basic
+examples:
+
+.. code-block:: cpp
+
+ void increment(int &i) { i++; }
+ void increment_ptr(int *i) { (*i)++; }
+
+In Python, all arguments are passed by reference, so there is no general
+issue in binding such code from Python.
+
+However, certain basic Python types (like ``str``, ``int``, ``bool``,
+``float``, etc.) are **immutable**. This means that the following attempt
+to port the function to Python doesn't have the same effect on the value
+provided by the caller -- in fact, it does nothing at all.
+
+.. code-block:: python
+
+ def increment(i):
+ i += 1 # nope..
+
+pybind11 is also affected by such language-level conventions, which means
+that binding ``increment`` or ``increment_ptr`` will also create Python functions that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types
+in a custom type that does allow modifications.
diff --git a/docs/index.rst b/docs/index.rst
index b9afea5..a06a46c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,5 +14,6 @@
advanced
cmake
benchmark
+ faq
reference
changelog