diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 48e3d82b..ddefadcb 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -6,7 +6,7 @@ Change Log
 All notable changes to this code base will be documented in this file,
 in every released version.
 
-Version 2.9.x (WIP)
+Version 2.10.0 (WIP)
 ===================
 
 :Released: 2020-xx-yy
@@ -15,6 +15,10 @@ Version 2.9.x (WIP)
 Features
 --------
 
+* :pr:`235`: Improved documentation and shift focus on ``semver.VersionInfo`` instead of advertising
+  the old and deprecated module-level functions.
+
+
 Bug Fixes
 ---------
 
diff --git a/README.rst b/README.rst
index 862fbdc6..265aac46 100644
--- a/README.rst
+++ b/README.rst
@@ -9,18 +9,23 @@ A Python module for `semantic versioning`_. Simplifies comparing versions.
 
 .. teaser-end
 
-.. note::
+.. warning::
 
-   With version 2.9.0 we've moved the GitHub project. The project is now
-   located under the organization ``python-semver``.
-   The complete URL is::
+   As anything comes to an end, this project will focus on Python 3.x only.
+   New features and bugfixes will be integrated into the 3.x.y branch only.
 
-       https://github.com/python-semver/python-semver
+   Major version 3 of semver will contain some incompatible changes:
 
-   If you still have an old repository, correct your upstream URL to the new URL::
+   * removes support for Python 2.7 and 3.3
+   * removes deprecated functions (see :ref:`sec_replace_deprecated_functions` for
+     further information).
 
-       $ git remote set-url upstream git@github.com:python-semver/python-semver.git
+   The last version of semver which supports Python 2.7 and 3.4 will be
+   2.10.x. However, keep in mind, version 2.10.x is frozen: no new
+   features nor backports will be integrated.
 
+   We recommend to upgrade your workflow to Python 3.x to gain support,
+   bugfixes, and new features.
 
 The module follows the ``MAJOR.MINOR.PATCH`` style:
 
@@ -30,23 +35,6 @@ The module follows the ``MAJOR.MINOR.PATCH`` style:
 
 Additional labels for pre-release and build metadata are supported.
 
-
-.. warning::
-
-   Major version 3.0.0 of semver will remove support for Python 2.7 and 3.4.
-
-   As anything comes to an end, this project will focus on Python 3.x.
-   New features and bugfixes will be integrated only into the 3.x.y branch
-   of semver.
-
-   The last version of semver which supports Python 2.7 and 3.4 will be
-   2.9.x. However, keep in mind, version 2.9.x is frozen: no new
-   features nor backports will be integrated.
-
-   We recommend to upgrade your workflow to Python 3.x to gain support,
-   bugfixes, and new features.
-
-
 To import this library, use:
 
 .. code-block:: python
@@ -54,31 +42,29 @@ To import this library, use:
     >>> import semver
 
 Working with the library is quite straightforward. To turn a version string into the
-different parts, use the `semver.parse` function:
+different parts, use the ``semver.VersionInfo.parse`` function:
 
 .. code-block:: python
 
-    >>> ver = semver.parse('1.2.3-pre.2+build.4')
-    >>> ver['major']
+    >>> ver = semver.VersionInfo.parse('1.2.3-pre.2+build.4')
+    >>> ver.major
     1
-    >>> ver['minor']
+    >>> ver.minor
     2
-    >>> ver['patch']
+    >>> ver.patch
     3
-    >>> ver['prerelease']
+    >>> ver.prerelease
     'pre.2'
-    >>> ver['build']
+    >>> ver.build
     'build.4'
 
 To raise parts of a version, there are a couple of functions available for
-you. The `semver.parse_version_info` function converts a version string
-into a `semver.VersionInfo` class. The function
-`semver.VersionInfo.bump_major` leaves the original object untouched, but
-returns a new `semver.VersionInfo` instance with the raised major part:
+you. The function :func:`semver.VersionInfo.bump_major` leaves the original object untouched, but
+returns a new :class:`semver.VersionInfo` instance with the raised major part:
 
 .. code-block:: python
 
-    >>> ver = semver.parse_version_info("3.4.5")
+    >>> ver = semver.VersionInfo.parse("3.4.5")
     >>> ver.bump_major()
     VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)
 
diff --git a/docs/pysemver.rst b/docs/pysemver.rst
index 3c247b62..b0896eea 100644
--- a/docs/pysemver.rst
+++ b/docs/pysemver.rst
@@ -10,8 +10,7 @@ Synopsis
 
 .. code:: bash
 
-   pysemver compare <VERSION1> <VERSION2>
-   pysemver bump {major,minor,patch,prerelease,build} <VERSION>
+   pysemver <COMMAND> <OPTION>...
 
 
 Description
@@ -52,7 +51,7 @@ Bump a version.
 
 .. option:: <PART>
 
-    The part to bump. Valid strings can be ``major``, ``minor``,
+    The part to bump. Valid strings are ``major``, ``minor``,
     ``patch``, ``prerelease``, or ``build``. The part has the
     following effects:
 
diff --git a/docs/usage.rst b/docs/usage.rst
index cdf08b9a..91e4d069 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,11 +1,8 @@
 Using semver
 ============
 
-The ``semver`` module can store a version in different types:
-
-* as a string.
-* as :class:`semver.VersionInfo`, a dedicated class for a version type.
-* as a dictionary.
+The ``semver`` module can store a version in the :class:`semver.VersionInfo` class.
+For historical reasons, a version can be also stored as a string or dictionary.
 
 Each type can be converted into the other, if the minimum requirements
 are met.
@@ -32,15 +29,15 @@ creating a version:
 * through an object oriented approach with the :class:`semver.VersionInfo`
   class. This is the preferred method when using semver.
 
-* through module level functions and builtin datatypes (usually strings
-  and dicts).
-  These method are still available for compatibility reasons, but are
-  marked as deprecated. Using one of these will emit a DeprecationWarning.
+* through module level functions and builtin datatypes (usually string
+  and dict).
+  This method is still available for compatibility reasons, but are
+  marked as deprecated. Using it will emit a :class:`DeprecationWarning`.
 
 
 .. warning:: **Deprecation Warning**
 
-    Module level functions are marked as *deprecated* in version 2.9.2 now.
+    Module level functions are marked as *deprecated* in version 2.10.0 now.
     These functions will be removed in semver 3.
     For details, see the sections :ref:`sec_replace_deprecated_functions` and
     :ref:`sec_display_deprecation_warnings`.
@@ -48,7 +45,6 @@ creating a version:
 
 A :class:`semver.VersionInfo` instance can be created in different ways:
 
-
 * From a string::
 
     >>> semver.VersionInfo.parse("3.4.5-pre.2+build.4")
@@ -173,6 +169,8 @@ If you do, you get an ``AttributeError``::
     ...
     AttributeError: attribute 'minor' is readonly
 
+If you need to replace different parts of a version, refer to section :ref:`sec.replace.parts`.
+
 In case you need the different parts of a version stepwise, iterate over the :class:`semver.VersionInfo` instance::
 
     >>> for item in semver.VersionInfo.parse("3.4.5-pre.2+build.4"):
@@ -186,17 +184,13 @@ In case you need the different parts of a version stepwise, iterate over the :cl
     [3, 4, 5, 'pre.2', 'build.4']
 
 
+.. _sec.replace.parts:
+
 Replacing Parts of a Version
 ----------------------------
 
 If you want to replace different parts of a version, but leave other parts
-unmodified, use one of the functions :func:`semver.replace` or
-:func:`semver.VersionInfo.replace`:
-
-* From a version string::
-
-   >>> semver.replace("1.4.5-pre.1+build.6", major=2)
-   '2.4.5-pre.1+build.6'
+unmodified, use the function :func:`semver.VersionInfo.replace` or :func:`semver.replace`:
 
 * From a :class:`semver.VersionInfo` instance::
 
@@ -204,6 +198,11 @@ unmodified, use one of the functions :func:`semver.replace` or
    >>> version.replace(major=2, minor=2)
    VersionInfo(major=2, minor=2, patch=5, prerelease='pre.1', build='build.6')
 
+* From a version string::
+
+   >>> semver.replace("1.4.5-pre.1+build.6", major=2)
+   '2.4.5-pre.1+build.6'
+
 If you pass invalid keys you get an exception::
 
    >>> semver.replace("1.2.3", invalidkey=2)
@@ -251,29 +250,31 @@ Increasing Parts of a Version
 The ``semver`` module contains the following functions to raise parts of
 a version:
 
-* :func:`semver.bump_major`: raises the major part and set all other parts to
+* :func:`semver.VersionInfo.bump_major`: raises the major part and set all other parts to
   zero. Set ``prerelease`` and ``build`` to ``None``.
-* :func:`semver.bump_minor`: raises the minor part and sets ``patch`` to zero.
+* :func:`semver.VersionInfo.bump_minor`: raises the minor part and sets ``patch`` to zero.
   Set ``prerelease`` and ``build`` to ``None``.
-* :func:`semver.bump_patch`: raises the patch part. Set ``prerelease`` and
+* :func:`semver.VersionInfo.bump_patch`: raises the patch part. Set ``prerelease`` and
   ``build`` to ``None``.
-* :func:`semver.bump_prerelease`: raises the prerelease part and set
+* :func:`semver.VersionInfo.bump_prerelease`: raises the prerelease part and set
   ``build`` to ``None``.
-* :func:`semver.bump_build`: raises the build part.
+* :func:`semver.VersionInfo.bump_build`: raises the build part.
 
 .. code-block:: python
 
-    >>> semver.bump_major("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_major())
     '4.0.0'
-    >>> semver.bump_minor("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_minor())
     '3.5.0'
-    >>> semver.bump_patch("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_patch())
     '3.4.6'
-    >>> semver.bump_prerelease("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_prerelease())
     '3.4.5-pre.3'
-    >>> semver.bump_build("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_build())
     '3.4.5-pre.2+build.5'
 
+Likewise the module level functions :func:`semver.bump_major`.
+
 
 Comparing Versions
 ------------------
@@ -405,11 +406,12 @@ For example:
 Replacing Deprecated Functions
 ------------------------------
 
-The development team of semver has decided to deprecate certain functions on
-the module level. The preferred way of using semver is through the
-:class:`semver.VersionInfo` class.
+.. versionchanged:: 2.10.0
+   The development team of semver has decided to deprecate certain functions on
+   the module level. The preferred way of using semver is through the
+   :class:`semver.VersionInfo` class.
 
-The deprecated functions can still be used in version 2.x.y. In version 3 of
+The deprecated functions can still be used in version 2.10.0 and above. In version 3 of
 semver, the deprecated functions will be removed.
 
 The following list shows the deprecated functions and how you can replace
diff --git a/semver.py b/semver.py
index aec5e9ef..de72f061 100644
--- a/semver.py
+++ b/semver.py
@@ -24,6 +24,7 @@
 if not hasattr(__builtins__, "cmp"):
 
     def cmp(a, b):
+        """Return negative if a<b, zero if a==b, positive if a>b."""
         return (a > b) - (a < b)
 
 
@@ -31,15 +32,13 @@ def deprecated(func=None, replace=None, version=None, category=DeprecationWarnin
     """
     Decorates a function to output a deprecation warning.
 
-    This function will be removed once major version 3 of semver is
-    released.
-
+    :param func: the function to decorate (or None)
     :param str replace: the function to replace (use the full qualified
         name like ``semver.VersionInfo.bump_major``.
     :param str version: the first version when this function was deprecated.
     :param category: allow you to specify the deprecation warning class
         of your choice. By default, it's  :class:`DeprecationWarning`, but
-        you can choose :class:`PendingDeprecationWarning``or a custom class.
+        you can choose :class:`PendingDeprecationWarning` or a custom class.
     """
 
     if func is None:
@@ -79,12 +78,12 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def parse(version):
     """
     Parse version to major, minor, patch, pre-release, build parts.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.parse` instead.
 
     :param version: version string
@@ -169,7 +168,7 @@ def __init__(self, major, minor=0, patch=0, prerelease=None, build=None):
 
     @property
     def major(self):
-        """The major part of a version."""
+        """The major part of a version (read-only)."""
         return self._major
 
     @major.setter
@@ -178,7 +177,7 @@ def major(self, value):
 
     @property
     def minor(self):
-        """The minor part of a version."""
+        """The minor part of a version (read-only)."""
         return self._minor
 
     @minor.setter
@@ -187,7 +186,7 @@ def minor(self, value):
 
     @property
     def patch(self):
-        """The patch part of a version."""
+        """The patch part of a version (read-only)."""
         return self._patch
 
     @patch.setter
@@ -196,7 +195,7 @@ def patch(self, value):
 
     @property
     def prerelease(self):
-        """The prerelease part of a version."""
+        """The prerelease part of a version (read-only)."""
         return self._prerelease
 
     @prerelease.setter
@@ -205,7 +204,7 @@ def prerelease(self, value):
 
     @property
     def build(self):
-        """The build part of a version."""
+        """The build part of a version (read-only)."""
         return self._build
 
     @build.setter
@@ -216,7 +215,7 @@ def to_tuple(self):
         """
         Convert the VersionInfo object to a tuple.
 
-        .. versionadded:: 2.9.2
+        .. versionadded:: 2.10.0
            Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
            make this function available in the public API.
 
@@ -232,7 +231,7 @@ def to_dict(self):
         """
         Convert the VersionInfo object to an OrderedDict.
 
-        .. versionadded:: 2.9.2
+        .. versionadded:: 2.10.0
            Renamed ``VersionInfo._asdict`` to ``VersionInfo.to_dict`` to
            make this function available in the public API.
 
@@ -255,13 +254,13 @@ def to_dict(self):
         )
 
     # For compatibility reasons:
-    @deprecated(replace="semver.VersionInfo.to_tuple", version="2.9.2")
+    @deprecated(replace="semver.VersionInfo.to_tuple", version="2.10.0")
     def _astuple(self):
         return self.to_tuple()  # pragma: no cover
 
     _astuple.__doc__ = to_tuple.__doc__
 
-    @deprecated(replace="semver.VersionInfo.to_dict", version="2.9.2")
+    @deprecated(replace="semver.VersionInfo.to_dict", version="2.10.0")
     def _asdict(self):
         return self.to_dict()  # pragma: no cover
 
@@ -299,7 +298,7 @@ def bump_major(self):
         :return: new object with the raised major part
         :rtype: VersionInfo
 
-        >>> ver = semver.parse_version_info("3.4.5")
+        >>> ver = semver.VersionInfo.parse("3.4.5")
         >>> ver.bump_major()
         VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)
         """
@@ -314,7 +313,7 @@ def bump_minor(self):
         :return: new object with the raised minor part
         :rtype: VersionInfo
 
-        >>> ver = semver.parse_version_info("3.4.5")
+        >>> ver = semver.VersionInfo.parse("3.4.5")
         >>> ver.bump_minor()
         VersionInfo(major=3, minor=5, patch=0, prerelease=None, build=None)
         """
@@ -329,7 +328,7 @@ def bump_patch(self):
         :return: new object with the raised patch part
         :rtype: VersionInfo
 
-        >>> ver = semver.parse_version_info("3.4.5")
+        >>> ver = semver.VersionInfo.parse("3.4.5")
         >>> ver.bump_patch()
         VersionInfo(major=3, minor=4, patch=6, prerelease=None, build=None)
         """
@@ -345,7 +344,7 @@ def bump_prerelease(self, token="rc"):
         :return: new object with the raised prerelease part
         :rtype: str
 
-        >>> ver = semver.parse_version_info("3.4.5-rc.1")
+        >>> ver = semver.VersionInfo.parse("3.4.5-rc.1")
         >>> ver.bump_prerelease()
         VersionInfo(major=3, minor=4, patch=5, prerelease='rc.2', \
 build=None)
@@ -363,7 +362,7 @@ def bump_build(self, token="build"):
         :return: new object with the raised build part
         :rtype: str
 
-        >>> ver = semver.parse_version_info("3.4.5-rc.1+build.9")
+        >>> ver = semver.VersionInfo.parse("3.4.5-rc.1+build.9")
         >>> ver.bump_build()
         VersionInfo(major=3, minor=4, patch=5, prerelease='rc.1', \
 build='build.10')
@@ -432,6 +431,7 @@ def parse(version):
 
         :param version: version string
         :return: a :class:`semver.VersionInfo` instance
+        :raises: :class:`ValueError`
         :rtype: :class:`semver.VersionInfo`
 
         >>> semver.VersionInfo.parse('3.4.5-pre.2+build.4')
@@ -462,7 +462,7 @@ def replace(self, **parts):
           ``major``, ``minor``, ``patch``, ``prerelease``, or ``build``
         :return: the new :class:`semver.VersionInfo` object with the changed
           parts
-        :raises: TypeError, if ``parts`` contains invalid keys
+        :raises: :class:`TypeError`, if ``parts`` contains invalid keys
         """
         version = self.to_dict()
         version.update(parts)
@@ -503,25 +503,22 @@ def _to_dict(obj):
     return obj
 
 
-@deprecated(replace="semver.VersionInfo.parse", version="2.9.2")
+@deprecated(replace="semver.VersionInfo.parse", version="2.10.0")
 def parse_version_info(version):
     """
     Parse version string to a VersionInfo instance.
 
-    .. versionadded:: 2.7.2
-       Added :func:`parse_version_info`
-
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.parse` instead.
 
     .. versionadded:: 2.7.2
-       Added :func:`parse_version_info`
+       Added :func:`semver.parse_version_info`
 
     :param version: version string
     :return: a :class:`VersionInfo` instance
     :rtype: :class:`VersionInfo`
 
-    >>> version_info = semver.parse_version_info("3.4.5-pre.2+build.4")
+    >>> version_info = semver.VersionInfo.parse("3.4.5-pre.2+build.4")
     >>> version_info.major
     3
     >>> version_info.minor
@@ -693,12 +690,12 @@ def min_ver(ver1, ver2):
         return ver2
 
 
-@deprecated(replace="str(versionobject)", version="2.9.2")
+@deprecated(replace="str(versionobject)", version="2.10.0")
 def format_version(major, minor, patch, prerelease=None, build=None):
     """
     Format a version string according to the Semantic Versioning specification.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use ``str(VersionInfo(VERSION)`` instead.
 
     :param int major: the required major part of a version
@@ -715,12 +712,12 @@ def format_version(major, minor, patch, prerelease=None, build=None):
     return str(VersionInfo(major, minor, patch, prerelease, build))
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def bump_major(version):
     """
     Raise the major part of the version string.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.bump_major` instead.
 
     :param: version string
@@ -733,12 +730,12 @@ def bump_major(version):
     return str(VersionInfo.parse(version).bump_major())
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def bump_minor(version):
     """
     Raise the minor part of the version string.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.bump_minor` instead.
 
     :param: version string
@@ -751,12 +748,12 @@ def bump_minor(version):
     return str(VersionInfo.parse(version).bump_minor())
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def bump_patch(version):
     """
     Raise the patch part of the version string.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.bump_patch` instead.
 
     :param: version string
@@ -769,12 +766,12 @@ def bump_patch(version):
     return str(VersionInfo.parse(version).bump_patch())
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def bump_prerelease(version, token="rc"):
     """
     Raise the prerelease part of the version string.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.bump_prerelease` instead.
 
     :param version: version string
@@ -788,12 +785,12 @@ def bump_prerelease(version, token="rc"):
     return str(VersionInfo.parse(version).bump_prerelease(token))
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def bump_build(version, token="build"):
     """
     Raise the build part of the version string.
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.bump_build` instead.
 
     :param version: version string
@@ -807,7 +804,7 @@ def bump_build(version, token="build"):
     return str(VersionInfo.parse(version).bump_build(token))
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def finalize_version(version):
     """
     Remove any prerelease and build metadata from the version string.
@@ -815,7 +812,7 @@ def finalize_version(version):
     .. versionadded:: 2.7.9
        Added :func:`finalize_version`
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.finalize_version` instead.
 
     :param version: version string
@@ -829,7 +826,7 @@ def finalize_version(version):
     return str(verinfo.finalize_version())
 
 
-@deprecated(version="2.9.2")
+@deprecated(version="2.10.0")
 def replace(version, **parts):
     """
     Replace one or more parts of a version and return the new string.
@@ -837,7 +834,7 @@ def replace(version, **parts):
     .. versionadded:: 2.9.0
        Added :func:`replace`
 
-    .. deprecated:: 2.9.2
+    .. deprecated:: 2.10.0
        Use :func:`semver.VersionInfo.replace` instead.
 
     :param str version: the version string to replace