diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc
index c87a8b8b4..4c704d8f0 100644
--- a/docs/usage_general.rst.inc
+++ b/docs/usage_general.rst.inc
@@ -1,3 +1,20 @@
+Positional Arguments and Options: Order matters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Borg only supports taking options (``-s`` and ``--progress`` in the example)
+to the left or right of all positional arguments (``repo::archive`` and ``path``
+in the example), but not in between them:
+
+::
+
+    borg create -s --progress repo::archive path  # good and preferred
+    borg create repo::archive path -s --progress  # also works
+    borg create -s repo::archive path --progress  # works, but ugly
+    borg create repo::archive -s --progress path  # BAD
+
+This is due to a problem in the argparse module: http://bugs.python.org/issue15112
+
+
 Repository URLs
 ~~~~~~~~~~~~~~~