diff --git a/docs/userguide.rst b/docs/userguide.rst
index a6b1c5b..ae677ea 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -273,6 +273,44 @@ come from the same repository or have to live outside of any versioning control.
 kas will refuse any other combination in order to avoid complications and
 configuration flaws that can easily emerge from them.
 
+Working with lockfiles
+~~~~~~~~~~~~~~~~~~~~~~
+
+KAS supports the use of lockfiles to pinpoint repositories to exact refspecs
+(e.g. SHA-1 refs for git). A lockfile hereby only overrides the refspecs
+defined in a kas file. When performing the checkout operation (or any other
+operation that performs a checkout), kas checks if a file named
+``<filename>.lock.<ext>`` is found next to the first file stated on the kas
+cmdline. If this is found, kas appends this filename to the kas cmdline and
+performs the requested operation.
+
+The following example shows this mechanism for a file ``kas/kas-isar.yml``
+and its corresponding lockfile ``kas/kas-isar.lock.yml``.
+
+ ``kas/kas-isar.yml``:
+
+.. code-block:: yaml
+
+  # [...]
+  repos:
+    isar:
+      url: https://github.com/ilbers/isar.git
+      refspec: next
+
+``kas/kas-isar.lock.yml``:
+
+.. code-block:: yaml
+
+  header:
+    version: 14
+  overrides:
+    repos:
+      isar:
+        refspec: 0336610df8bb0adce76ef8c5a921c758efed9f45
+
+The ``dump`` plugin provides helpers to simplify the creation and update
+of lockfiles. For details, see the plugins documentation: :mod:`kas.plugins.dump`.
+
 Configuration reference
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/kas/includehandler.py b/kas/includehandler.py
index c42b227..8d1d274 100644
--- a/kas/includehandler.py
+++ b/kas/includehandler.py
@@ -123,9 +123,10 @@ class IncludeHandler:
 
         The includes are read and merged from the deepest level upwards.
 
-        In case ignore_lock is false, kas checks if a file <file>.lock.<ext>
-        exists next to the first entry in top_files. This file is then appended
-        to the list of top_files.
+        In case ``ignore_lock`` is ``false``, kas checks if a file
+        ``<file>.lock.<ext>`` exists next to the first entry in
+        ``top_files``. This filename is then appended to the list of
+        ``top_files``.
     """
 
     def __init__(self, top_files, top_repo_path, use_lock=True):
diff --git a/kas/plugins/dump.py b/kas/plugins/dump.py
index dda8ecc..e59d75c 100644
--- a/kas/plugins/dump.py
+++ b/kas/plugins/dump.py
@@ -29,9 +29,12 @@
     files. The output of this command can be used to further analyse the build
     configuration.
 
-    When running with --lock, a lock-file is created which only contains the
-    exact refspecs of each repository. This file can be used to pin the
+    When running with ``--lock``, a locking spec is created which only contains
+    the exact refspecs of each repository. This can be used to pin the
     refspecs of floating branches, while still keeping an easy update path.
+    When combining with ``--inplace``, a lockfile is created next to the
+    first file on the kas cmdline. For details on the locking support, see
+    :class:`kas.includehandler.IncludeHandler`.
 
     Please note:
 
@@ -48,14 +51,16 @@
 
         kas build kas-project-expanded.yml
 
-    Example of the locking mechanism (call again to regenerate lockfile):
+    Example of the locking mechanism (call again to regenerate lockfile).
+    The lockfile is created as ``kas-project.lock.yml``::
 
         kas dump --lock --inplace --update kas-project.yml
 
-    The generated lockfile will automatically be used to pin the revisions:
+    The generated lockfile will automatically be used to pin the revisions::
 
         kas build kas-project.yml
 
+    Note, that the lockfiles should be checked-in into the VCS.
 """
 
 import logging