diff --git a/documenting.rst b/documenting.rst
--- a/documenting.rst
+++ b/documenting.rst
@@ -1199,33 +1199,35 @@ units as well as normal text:
 
 .. describe:: versionadded
 
    This directive documents the version of Python which added the described
    feature, or a part of it, to the library or C API.  When this applies to an
    entire module, it should be placed at the top of the module section before
    any prose.
 
-   The first argument must be given and is the version in question; if the
-   addition is only part of the described API element, you should add a second
-   argument consisting of a *brief* explanation of the change.
+   The first argument must be given and is the version in question.
 
    Example::
 
-      .. versionadded:: 3.1
-         The *spam* parameter.
-
-   Note that there must be no blank line between the directive head and the
-   explanation; this is to make these blocks visually continuous in the markup.
+      .. versionadded:: 3.5
 
 .. describe:: versionchanged
 
    Similar to ``versionadded``, but describes when and what changed in the named
-   feature in some way (changed side effects, platform support, etc.).  This one
-   *must* have the second argument (explanation of the change).
+   feature in some way (new parameters, changed side effects, platform support,
+   etc.).  This one *must* have the second argument (explanation of the change).
+
+   Example::
+
+      .. versionchanged:: 3.1
+         The *spam* parameter was added.
+
+   Note that there must be no blank line between the directive head and the
+   explanation; this is to make these blocks visually continuous in the markup.
 
 --------------
 
 .. describe:: impl-detail
 
    This directive is used to mark CPython-specific information.  Use either with
    a block content or a single sentence as an argument, i.e. either ::