diff --git a/python/doc/api.rst b/python/doc/api.rst
index d82364b75..049bc2928 100644
--- a/python/doc/api.rst
+++ b/python/doc/api.rst
@@ -2,10 +2,6 @@
 high level API reference
 ========================
 
-.. note::
-
-    This API is work in progress and may change in versions prior to 1.0.
-
 - :class:`deltachat.account.Account` (your main entry point, creates the
   other classes)
 - :class:`deltachat.contact.Contact`
diff --git a/python/doc/plugins.rst b/python/doc/plugins.rst
index 6b37d19ea..1c4a5a619 100644
--- a/python/doc/plugins.rst
+++ b/python/doc/plugins.rst
@@ -4,15 +4,21 @@ Implementing Plugin Hooks
 
 The Delta Chat Python bindings use `pluggy <https://pluggy.readthedocs.io>`_
 for managing global and per-account plugin registration, and performing
-hook calls.
+hook calls. There are two kinds of plugins:
+
+- Global plugins that are active for all accounts; they can implement
+  hooks at account-creation and account-shutdown time.
+
+- Account plugins that are only active during the lifetime of a
+  single Account instance.
 
 
 Registering a plugin
 --------------------
 
-.. autoclass:: deltachat.register_global_plugin
+.. autofunction:: deltachat.register_global_plugin
 
-.. autoclass:: deltachat.account.Account.add_account_plugin
+.. automethod:: deltachat.account.Account.add_account_plugin
 
 
 Per-Account Hook specifications
diff --git a/python/src/deltachat/__init__.py b/python/src/deltachat/__init__.py
index 4630c7ea6..ac27a4209 100644
--- a/python/src/deltachat/__init__.py
+++ b/python/src/deltachat/__init__.py
@@ -79,7 +79,7 @@ def get_dc_event_name(integer, _DC_EVENTNAME_MAP={}):
 
 def register_global_plugin(plugin):
     """ Register a global plugin which implements one or more
-    of the :class:`deltachat.hookspec.Global` specs.
+    of the :class:`deltachat.hookspec.Global` hooks.
     """
     gm = hookspec.Global._get_plugin_manager()
     gm.register(plugin)
diff --git a/python/src/deltachat/account.py b/python/src/deltachat/account.py
index 70f2eac8e..eaf8ee615 100644
--- a/python/src/deltachat/account.py
+++ b/python/src/deltachat/account.py
@@ -160,6 +160,7 @@ class Account(object):
 
     def update_config(self, kwargs):
         """ update config values.
+
         :param kwargs: name=value config settings for this account.
                        values need to be unicode.
         :returns: None
@@ -529,7 +530,7 @@ class Account(object):
 
     def add_account_plugin(self, plugin):
         """ add an account plugin which implements one or more of
-        the :class:`deltachat.hookspec.PerAccount` specs.
+        the :class:`deltachat.hookspec.PerAccount` hooks.
         """
         self._pm.register(plugin)
         self._pm.check_pending()
diff --git a/python/src/deltachat/hookspec.py b/python/src/deltachat/hookspec.py
index 15bf7eb94..d8868f150 100644
--- a/python/src/deltachat/hookspec.py
+++ b/python/src/deltachat/hookspec.py
@@ -53,7 +53,8 @@ class PerAccount:
 
 
 class Global:
-    """ global hook specifications using a per-process singleton plugin manager instance.
+    """ global hook specifications using a per-process singleton
+    plugin manager instance.
 
     """
     _plugin_manager = None