diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index 221f06a09769895d4410981d8a60929ecec9a93c..406e5ae5f3498fc5c0ad3185ad1ff74ed390992f 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -6,7 +6,8 @@ problem. This document describes what you can do.
 
 .. note::
    ``cluster$`` indicates that the commands should be run as root on your
-   Stackspin machine.
+   Stackspin machine. All other commands need to be run on your *provisioning
+   machine*.
 
 **We would love to hear from you!** If you have problems, please create an issue
 in our `issue tracker
@@ -30,8 +31,8 @@ Run the CLI tests
 To get an overall status of your cluster you can run the tests from the
 command line.
 
-There are two types of tests: [testinfra](https://testinfra.readthedocs.io/en/latest/)
-tests, and [Taiko](https://taiko.dev) tests.
+There are two types of tests: `testinfra <https://testinfra.readthedocs.io/en/latest/>`__
+tests, and `Taiko <https://taiko.dev>`__ tests.
 
 Testinfra tests
 ~~~~~~~~~~~~~~~
@@ -97,7 +98,7 @@ Known Issues
 
 The default ssh backend for testinfra tests is ``paramiko``, which doesn't work
 out of the box. It fails to connect to the host because the ``ed25519`` hostkey
-was not verified. Therefore we need to force plain ssh:// with either
+was not verified. Therefore we need to force plain ``ssh://`` with either
 ``connection=ssh`` or ``--hosts=ssh://…``
 
 Taiko tests
@@ -110,7 +111,7 @@ and running and correctly connected to each other. They are integrated in the
 Prerequisites
 '''''''''''''
 
-Install [Taiko](https://taiko.dev) on your provisioning machine:
+Install `Taiko <https://taiko.dev>`__ on your provisioning machine:
 
 .. code:: bash