diff --git a/docs/basics.rst b/docs/basics.rst
index 73d217072..1f40f198d 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -177,6 +177,21 @@ The keyword names also appear in the function signatures within the documentatio
 
             A function which adds two numbers
 
+A shorter notation for named arguments is also available:
+
+.. code-block:: cpp
+    
+    // regular notation
+    m.def("add1", &add, py::arg("i"), py::arg("j"));
+    // shorthand
+    using namespace pybind11::literals;
+    m.def("add2", &add, "i"_a, "j"_a);
+
+The :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`. 
+Note that the literal operator must first be made visible with the directive 
+``using namespace pybind11::literals``. This does not bring in anything else 
+from the ``pybind11`` namespace except for literals.
+
 .. _default_args:
 
 Default arguments
@@ -213,6 +228,15 @@ The default values also appear within the documentation.
 
             A function which adds two numbers
 
+The shorthand notation is also available for default arguments:
+
+.. code-block:: cpp
+    
+    // regular notation
+    m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2);
+    // shorthand
+    m.def("add2", &add, "i"_a=1, "j"_a=2);
+
 .. _supported_types:
 
 Supported data types
@@ -283,4 +307,3 @@ as arguments and return values, refer to the section on binding :ref:`classes`.
 
 .. [#f1] In practice, implementation and binding code will generally be located
          in separate files.
-