diff --git a/docs/source/stubtest.rst b/docs/source/stubtest.rst
index 828931fbdf2b..ca291f55947e 100644
--- a/docs/source/stubtest.rst
+++ b/docs/source/stubtest.rst
@@ -72,7 +72,7 @@ Here's a quick example of what stubtest can do:
     Stub: at line 1
     builtins.int
     Runtime:
-    hello, stubtest
+    'hello, stubtest'
 
 
 Usage
@@ -86,7 +86,14 @@ is installed in the same environment as the library to be tested. In some
 cases, setting ``PYTHONPATH`` can help stubtest find the code to import.
 
 Similarly, stubtest must be able to find the stubs to be checked. Stubtest
-respects the ``MYPYPATH`` environment variable.
+respects the ``MYPYPATH`` environment variable -- consider using this if you
+receive a complaint along the lines of "failed to find stubs".
+
+Note that stubtest requires mypy to be able to analyse stubs. If mypy is unable
+to analyse stubs, you may get an error on the lines of "not checking stubs due
+to mypy build errors". In this case, you will need to mitigate those errors
+before stubtest will run. Despite potential overlap in errors here, stubtest is
+not intended as a substitute for running mypy directly.
 
 If you wish to ignore some of stubtest's complaints, stubtest supports a
 pretty handy allowlist system.