diff --git a/README b/README
index 744c6bceab961925d07d2f72f2e607fb3445b98f..c89d5bb17fc51b134ed9ab1bb116611fee3c8c91 100644
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
 Ganeti 2.5
 ==========
 
-For installation instructions, read the INSTALL and the doc/install.html
+For installation instructions, read the INSTALL and the doc/install.rst
 files.
 
 For a brief introduction, read the ganeti(7) manpage and the other pages
diff --git a/doc/rapi.rst b/doc/rapi.rst
index 84281f20694968bd5b1fe6754f0b3e6acfea19eb..9a15e908f73fd2f9e67a226caa84c84933fa0db3 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -53,8 +53,8 @@ Example::
 
 
 .. [#pwhash] Using the MD5 hash of username, realm and password is
-   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 and
-   3.3. The reason for using it over another algorithm is forward
+   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
+   and 3.3. The reason for using it over another algorithm is forward
    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
    authentication in the future, the same hash could be used.
    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
diff --git a/lib/rapi/rlib2.py b/lib/rapi/rlib2.py
index db004f1417a4da103e7bf2c6d18c89fa1608a33a..ab54c2592b2ccfc7172b18268539f2799e37d43d 100644
--- a/lib/rapi/rlib2.py
+++ b/lib/rapi/rlib2.py
@@ -19,21 +19,35 @@
 # 02110-1301, USA.
 
 
-"""Remote API version 2 baserlib.library.
-
-  PUT or POST?
-  ============
-
-  According to RFC2616 the main difference between PUT and POST is that
-  POST can create new resources but PUT can only create the resource the
-  URI was pointing to on the PUT request.
-
-  To be in context of this module for instance creation POST on
-  /2/instances is legitim while PUT would be not, due to it does create a
-  new entity and not just replace /2/instances with it.
-
-  So when adding new methods, if they are operating on the URI entity itself,
-  PUT should be prefered over POST.
+"""Remote API resource implementations.
+
+PUT or POST?
+============
+
+According to RFC2616 the main difference between PUT and POST is that
+POST can create new resources but PUT can only create the resource the
+URI was pointing to on the PUT request.
+
+In the context of this module POST on ``/2/instances`` to chance an existing
+entity is legitimate, while PUT would not be. PUT creates a new entity (e.g. a
+new instance) with a name specified in the request.
+
+Quoting from RFC2616, section 9.6:
+
+  The fundamental difference between the POST and PUT requests is reflected in
+  the different meaning of the Request-URI. The URI in a POST request
+  identifies the resource that will handle the enclosed entity. That resource
+  might be a data-accepting process, a gateway to some other protocol, or a
+  separate entity that accepts annotations. In contrast, the URI in a PUT
+  request identifies the entity enclosed with the request -- the user agent
+  knows what URI is intended and the server MUST NOT attempt to apply the
+  request to some other resource. If the server desires that the request be
+  applied to a different URI, it MUST send a 301 (Moved Permanently) response;
+  the user agent MAY then make its own decision regarding whether or not to
+  redirect the request.
+
+So when adding new methods, if they are operating on the URI entity itself,
+PUT should be prefered over POST.
 
 """