diff --git a/doc/doctest.txt b/doc/doctest.txt
index b7ca3465f..cafa77aa1 100644
--- a/doc/doctest.txt
+++ b/doc/doctest.txt
@@ -21,3 +21,34 @@ putting them into a conftest.py file like this::
     option_doctestmodules = True
     option_doctestglob = "*.rst"
 
+If you then have a text file like this::
+
+    # content of example.rst
+
+    hello this is a doctest
+    >>> x = 3
+    >>> x
+    3
+
+and another like this::
+
+    # content of mymodule.py
+    def something():
+        """ a doctest in a docstring
+        >>> something()  
+        42
+        """
+        return 42
+
+then you can just invoke ``py.test`` without command line options::
+
+    $ py.test
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+    test path 1: /tmp/doc-exec-109
+    
+    conftest.py .
+    example.rst .
+    mymodule.py .
+    
+    =========================== 3 passed in 0.01 seconds ===========================
diff --git a/doc/funcargs.txt b/doc/funcargs.txt
index f3d4f1fcb..78390c279 100644
--- a/doc/funcargs.txt
+++ b/doc/funcargs.txt
@@ -31,25 +31,23 @@ into a test module::
 Running the test looks like this::
 
     $ py.test test_simplefactory.py
-
-    =========================== test session starts ============================
-    python: platform linux2 -- Python 2.6.2
-    test object 1: /home/hpk/hg/py/trunk/example/funcarg/test_simplefactory.py
-
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+    test path 1: test_simplefactory.py
+    
     test_simplefactory.py F
-
-    ================================ FAILURES ==================================
-    ______________________________ test_function _______________________________
-
+    
+    =================================== FAILURES ===================================
+    ________________________________ test_function _________________________________
+    
     myfuncarg = 42
-
+    
         def test_function(myfuncarg):
     >       assert myfuncarg == 17
     E       assert 42 == 17
-
-    test_simplefactory.py:6: AssertionError
-    ======================== 1 failed in 0.11 seconds ==========================
-
+    
+    test_simplefactory.py:5: AssertionError
+    =========================== 1 failed in 0.02 seconds ===========================
 
 This means that the test function was called with a ``myfuncarg`` value
 of ``42`` and the assert fails accordingly.  Here is how py.test
@@ -143,23 +141,23 @@ Let's consider this test module::
 Running this::
 
     $ py.test test_example.py
-    ============================= test session starts ==========================
-    python: platform linux2 -- Python 2.6.2
-    test object 1: /home/hpk/hg/py/trunk/test_example.py
-
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+    test path 1: test_example.py
+    
     test_example.py .........F
-
-    ================================ FAILURES ==================================
-    __________________________ test_func.test_func[9] __________________________
-
+    
+    =================================== FAILURES ===================================
+    _________________________________ test_func[9] _________________________________
+    
     numiter = 9
-
+    
         def test_func(numiter):
     >       assert numiter < 9
     E       assert 9 < 9
-
-    /home/hpk/hg/py/trunk/test_example.py:10: AssertionError
-
+    
+    test_example.py:7: AssertionError
+    ====================== 1 failed, 9 passed in 0.04 seconds ======================
 
 Here is what happens in detail:
 
diff --git a/doc/monkeypatch.txt b/doc/monkeypatch.txt
index e4ca43ca5..8bb8eea00 100644
--- a/doc/monkeypatch.txt
+++ b/doc/monkeypatch.txt
@@ -27,18 +27,22 @@ patch this function before calling into a function which uses it::
         return os.path.join(os.expanduser("~admin"), '.ssh')
 
     def test_mytest(monkeypatch):
-        monkeypatch.setattr(os.path, 'expanduser', lambda x: '/tmp/xyz')
+        def mockreturn(path):
+            return '/abc'
+        monkeypatch.setattr(os.path, 'expanduser', mockreturn)
         x = getssh()
-        assert x == '/tmp/xyz/.ssh'
+        assert x == '/abc'
 
 After the test function finishes the ``os.path.expanduser`` modification
 will be undone.
 
-Running the above example::
-    
-    $ py.test
-    PASS
-
+.. background check:
+   $ py.test
+   ============================= test session starts ==============================
+   platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+   test path 1: /tmp/doc-exec-117
+   
+   ===============================  in 0.00 seconds ===============================
 
 Method reference of the monkeypatch function argument
 -----------------------------------------------------
diff --git a/doc/reporting.txt b/doc/reporting.txt
index 0d3d268e6..ad7d0d285 100644
--- a/doc/reporting.txt
+++ b/doc/reporting.txt
@@ -5,9 +5,9 @@ creating JUnitXML format files
 ----------------------------------------------------
 
 To create result files which can be read by Hudson_ or other Continous
-integration servers, use this::
+integration servers, use this invocation::
 
-    $ py.test --junitxml=path
+    py.test --junitxml=path
 
 to create an XML file at ``path``.
 
@@ -16,7 +16,7 @@ creating resultlog format files
 
 To create plain-text machine-readable result files you can issue::
 
-    $ py.test --resultlog=path
+    py.test --resultlog=path
 
 and look at the content at the ``path`` location.  Such files are used e.g.
 by the `PyPy-test`_ web page to show test results over several revisions.