diff --git a/py/doc/misc.txt b/py/doc/misc.txt
index a7471869a..865708445 100644
--- a/py/doc/misc.txt
+++ b/py/doc/misc.txt
@@ -184,30 +184,29 @@ sources:
   * :source:`py/compat/`
   * :source:`py/builtin/`
 
-The py-lib contains some helpers that make writing scripts that work on various
-Python versions easier.
+The compat and builtin namespaces help to write code using newer python features on older python interpreters. 
 
 :api:`py.compat`
 ----------------
 
-:api:`py.compat` provides fixed versions (currently from Python 2.4.4) of
-various newer modules to be able to use them in various Python versions.
-Currently these are:
+:api:`py.compat` provides fixed versions (currently taken from Python 2.4.4) of
+a few selected modules to be able to use them across python versions.  Currently these are: 
 
  * doctest
  * optparse
  * subprocess
  * textwrap
 
-They are used by replacing the normal ``import ...`` by
-``from py.compat import ...``.
+Note that for example ``import doctest`` and ``from py.compat import doctest`` result
+into two different module objects no matter what Python version you are using.  
+So you should only use exactly one of these to avoid confusion in your program.  
 
 :api:`py.builtin`
 -----------------
 
-:api:`py.builtin` provides various builtins that were added in later Python
-versions. If the used Python version used does not provide these builtins, they
-are pure-Python reimplementations. These currently are:
+:api:`py.builtin` provides builtin functions/types that were added in later Python
+versions. If the used Python version used does not provide these builtins the
+py lib provides some reimplementations. These currently are:
 
  * enumerate
  * reversed
@@ -217,4 +216,3 @@ are pure-Python reimplementations. These currently are:
    module)
 
 :api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
-