diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
index 79a75536e..8c6740c26 100644
--- a/doc/usage/extensions/doctest.rst
+++ b/doc/usage/extensions/doctest.rst
@@ -11,11 +11,15 @@
            pair: testing; snippets
 
 
-This extension allows you to test snippets in the documentation in a natural
-way.  It works by collecting specially-marked up code blocks and running them as
-doctest tests.
+It is often helpful to include snippets of code in your documentation and
+demonstrate the results of executing it. But it is important to ensure that
+the documentation stays up-to-date with the code.
 
-Within one document, test code is partitioned in *groups*, where each group
+This extension allows you to test such code snippets in the documentation in
+a natural way.  If you mark the code blocks as shown here, the ``doctest''
+builder will collect them and run them as doctest tests.
+
+Within each document, you can assign each snippet to a *group*. Each group
 consists of:
 
 * zero or more *setup code* blocks (e.g. importing the module to test)