diff -r d5b0e1f4c5c5 -r abaae1496ba4 doc/book/en/devrepo/testing.rst
--- a/doc/book/en/devrepo/testing.rst	Fri Mar 14 11:18:15 2014 +0100
+++ b/doc/book/en/devrepo/testing.rst	Tue Mar 11 15:56:05 2014 +0100
@@ -466,29 +466,26 @@
 First, remember to think that some code run on a client side, some
 other on the repository side. More precisely:
 
-* client side: web interface, raw db-api connection (cubicweb-ctl shell for
+* client side: web interface, raw repoapi connection (cubicweb-ctl shell for
   instance);
 
 * repository side: RQL query execution, that may trigger hooks and operation.
 
-The client interact with the repository through a db-api connection.
+The client interacts with the repository through a repoapi connection.
 
 
-A db-api connection is tied to a session in the repository. The connection and
+A repoapi connection is tied to a session in the repository. The connection and
 request objects are unaccessible from repository code / the session object is
-unaccessible from client code (theorically at least).
+unaccessible from client code (theoretically at least).
 
-The :mod:`cubicweb.dbapi` module provides a base request class. The web interface
-provides an extended request class.
-
-
-The `request` object provides access to all cubicweb resources, eg:
+The web interface provides a request class.  That `request` object provides
+access to all cubicweb resources, eg:
 
 * the registry (which itself provides access to the schema and the
   configuration);
 
-* an underlying db-api connection (when using req.execute, you actually call the
-  db-api);
+* an underlying repoapi connection (when using req.execute, you actually call the
+  repoapi);
 
 * other specific resources depending on the client type (url generation according
   to base url, form parameters, etc.).
@@ -510,37 +507,32 @@
 The `_cw` attribute
 ```````````````````
 The `_cw` attribute available on every application object provides access to all
-cubicweb resources, eg:
+cubicweb resources, i.e.:
 
-For code running on the client side (eg web interface view), `_cw` is a request
-instance.
+- For code running on the client side (eg web interface view), `_cw` is a request
+  instance.
 
-For code running on the repository side (hooks and operation), `_cw` is a session
-instance.
+- For code running on the repository side (hooks and operation), `_cw` is a
+  Connection or Session instance.
 
 
-Beware some views may be called with a session (eg notifications) or with a
-DB-API request. In the later case, see :meth:`use_web_compatible_requests` on
-:class:`Connection` instances.
+Beware some views may be called with a session (e.g. notifications) or with a
+request.
 
 
 Request, session and transaction
 ````````````````````````````````
 
-In the web interface, an HTTP request is handle by a single request, which will
-be thrown way once the response send.
+In the web interface, an HTTP request is handled by a single request, which will
+be thrown away once the response is sent.
 
-The web publisher handle the transaction:
+The web publisher handles the transaction:
 
 * commit / rollback is done automatically
 * you should not commit / rollback explicitly
 
-When using a raw db-api, you're on your own regarding transaction.
-
-On the other hand, db-api connection and session live from a user login to its logout.
-
-Because session lives for a long time, and database connections is a limited
-resource, we can't bound a session to its own database connection for all its
+Because a session lives for a long time, and database connections are a limited
+resource, we can't bind a session to its own database connection for all its
 lifetime. The repository handles a pool of connections (4 by default), and it's
 responsible to attribute them as needed.
 
@@ -550,13 +542,13 @@
 
 2. the repository attributes a database connection to the session
 
-3. the repository's querier execute the query
+3. the repository's querier executes the query
 
 4. this query may trigger hooks. Hooks and operation may execute some rql queries
    through `_cw.execute`. Those queries go directly to the querier, hence don't
    touch the database connection, they use the one attributed in 2.
 
-5. the repository's get the result of the query in 1. If it was a RQL read query,
+5. the repository gets the result of the query in 1. If it was a RQL read query,
    the database connection is released. If it was a write query, the connection
    is then tied to the session until the transaction is commited or rollbacked.
 
@@ -567,11 +559,11 @@
 * when using a request, or code executed in hooks, this database connection
   handling is totally transparent
 
-* however, take care when writing test: you are usually faking / testing both the
-  server and the client side, so you have to decide when to use self.request() /
-  self.session. Ask yourself "where the code I want to test will be running,
-  client or repository side ?". The response is usually : use a request :)
-  However, if you really need using a session:
+* however, take care when writing tests: you are usually faking / testing both the
+  server and the client side, so you have to decide when to use RepoAccess.client_cnx /
+  RepoAccess.repo_cnx. Ask yourself "where the code I want to test will be running,
+  client or repository side ?". The response is usually : use a client connection :)
+  However, if you really need using a server-side object:
 
   - commit / rollback will free the database connection (unless explicitly told
     not to do so).