diff --git a/docs/Changelog.rst b/docs/Changelog.rst
index 5a3d5429..aff4af40 100644
--- a/docs/Changelog.rst
+++ b/docs/Changelog.rst
@@ -3,6 +3,9 @@
 Changelog for EasyBuild documentation
 -------------------------------------
 
+* **release 20150327.01** (`Mar 27th 2015`):
+
+  * documented deprecated functionality w.r.t. error reporting (see :ref:`depr_error_reporting`)
 * **release 20150316.01** (`Mar 16th 2015`):
 
   * include list of EasyBuild repositories cloned by ``install-EasyBuild-develop.sh`` script
diff --git a/docs/Deprecated-functionality.rst b/docs/Deprecated-functionality.rst
index 071d40c6..458cd32d 100644
--- a/docs/Deprecated-functionality.rst
+++ b/docs/Deprecated-functionality.rst
@@ -34,11 +34,43 @@ For authors of easyconfig files:
 
 For developers of easyblocks:
 
-*(nothing yet)*
+* :ref:`depr_error_reporting`
 
 For EasyBuild framework developers:
 
-*(nothing yet)*
+* :ref:`depr_error_reporting`
+
+.. _depr_error_reporting:
+
+Report errors by raising ``EasyBuildError`` rather than using log methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Use of the** ``error()`` **and** ``exception()`` **log methods is deprecated.**
+
+* *deprecated since:* EasyBuild v2.1.0 (April'15)
+* *removed in:* EasyBuild v3.0
+* *alternative(s)*: **use** ``raise EasyBuildError(...)`` **instead**
+
+The ``error()`` and ``exception()`` log methods defined by EasyBuild (in the ``easybuild.tools.build_log`` module)
+do not match the semantics of the `standard Python log methods
+<https://docs.python.org/2/library/logging.html#logging.Logger.error>`_, in the sense that they also raise an
+exception next to logging messages.
+
+This may cause problems when 3rd party libraries (e.g., `gc3pie <https://pypi.python.org/pypi/gc3pie>`_) are being
+used by EasyBuild, since they may be using these log methods without expecting an exception being raised.
+
+The custom definitions for the ``error()`` and ``exception()`` log methods will be removed in EasyBuild v3.0.
+
+Hence, these log methods should no longer be used to report errors since they will not raise an exception anymore once
+their custom definitions are removed. Note that this applies both to the EasyBuild framework and to (custom) easyblocks.
+
+To report errors, an ``EasyBuildError`` should be raised instead. For example:
+
+.. code::
+
+    # make sure config.sh script is there
+    if not os.path.exists(os.path.join(self.builddir, 'config.sh')):
+        raise EasyBuildError("config.sh script is missing in %s", self.builddir)
 
 .. _deprecation_policy:
 
diff --git a/docs/conf.py b/docs/conf.py
index d6adf8b9..62bce78d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -43,7 +43,7 @@
 # The short X.Y version.
 version = '2.0.0'  # this is meant to reference the version of EasyBuild
 # The full version, including alpha/beta/rc tags.
-release = '20150316.01'  # this is meant to reference the version of the documentation itself
+release = '20150327.01'  # this is meant to reference the version of the documentation itself
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used: