diff --git a/doc/source/api/object_versioning.rst b/doc/source/api/object_versioning.rst
index 23b8f9406a..3b86d4ed69 100644
--- a/doc/source/api/object_versioning.rst
+++ b/doc/source/api/object_versioning.rst
@@ -170,7 +170,7 @@ Example Using ``stack`` Mode
    versions of it, you must **DELETE** it five times.
 
 Example Using ``history`` Mode
-----------------------------
+------------------------------
 
 #.   Create the ``current`` container:
 
diff --git a/swift/common/middleware/versioned_writes.py b/swift/common/middleware/versioned_writes.py
index c8c48b761d..ecde0899c1 100644
--- a/swift/common/middleware/versioned_writes.py
+++ b/swift/common/middleware/versioned_writes.py
@@ -81,15 +81,22 @@ so this functionality was already available in previous releases and every
 attempt was made to maintain backwards compatibility. To allow operators to
 perform a seamless upgrade, it is not required to add the middleware to the
 proxy pipeline and the flag ``allow_versions`` in the container server
-configuration files are still valid. In future releases, ``allow_versions``
-will be deprecated in favor of adding this middleware to the pipeline to enable
-or disable the feature.
+configuration files are still valid, but only for ``stack`` mode. In future
+releases, ``allow_versions`` will be deprecated in favor of adding this
+middleware to the pipeline to enable or disable the feature.
 
 In case the middleware is added to the proxy pipeline, you must also
 set ``allow_versioned_writes`` to ``True`` in the middleware options
 to enable the information about this middleware to be returned in a /info
 request.
 
+ .. note::
+     You need to add the middleware to the proxy pipeline and set
+     ``allow_versioned_writes = True`` to use the ``history`` mode. Setting
+     ``allow_versions = True`` in the container server is not sufficient to
+     enable ``history`` mode.
+
+
 Upgrade considerations:
 +++++++++++++++++++++++