diff --git a/README.rst b/README.rst
index 33bdd2852..224696262 100644
--- a/README.rst
+++ b/README.rst
@@ -9,46 +9,112 @@ node managed by OpenStack Ironic. It fulfills the following tasks:
 
 * Initiating discovery for given nodes.
 * Managing iptables settings to allow/deny access to PXE boot server (usually
-  dnsmasq) for nodes under discovery.
+  *dnsmasq*) for nodes under discovery.
 * Receiving and processing data from discovery ramdisk booted on a node.
 
-Starting dnsmasq and configuring PXE boot environment is not part of this
+Starting *dnsmasq* and configuring PXE boot environment is not part of this
 package and should be done separately.
 
-Running
--------
+Installation
+------------
 
-We're available on PyPI::
+Package
+~~~~~~~
+
+Install package from PyPI (you may want to use virtualenv to isolate your
+environment)::
 
     pip install ironic-discoverd
-    ironic-discoverd /path/to/conf
 
-Or you can test locally::
+Copy ``example.conf`` to some permanent place
+(``/etc/ironic-discoverd/discoverd.conf`` is what we usually use). You have to
+fill in configuration values with names starting with *os_*. They configure
+how *ironic-discoverd* authenticates with Keystone.
 
-    make test_env  # only the first time
-    make test  # run tests
-    .env/bin/python setup.py develop
-    .env/bin/ironic-discoverd example.conf
+.. note::
+    Configuration file contains a password and thus should be owned by ``root``
+    and should have access rights like *0600*.
 
-Of course you may want to modify *example.conf* to match your OpenStack
+PXE Setup
+~~~~~~~~~
+
+* You need TFTP server running and accessible.
+* Build and put into your TFTP directory kernel and ramdisk from the
+  diskimage-builder_ `discovery-ironic element`_.
+* You need PXE boot server (e.g. *dnsmasq*) running on **the same** machine as
+  *ironic-discoverd*. Don't do any firewall configuration: *ironic-discoverd*
+  will handle it for you. In *ironic-discoverd* configuration file set
+  ``dnsmasq_interface`` to the interface your PXE boot server listens on.
+* Configure your ``$TFTPROOT/pxelinux.cfg/default`` with something like::
+
+    default discover
+
+    label discover
+    kernel discovery.kernel
+    append initrd=discovery.ramdisk
+    ironic_callback_url=http://{IP}:5050/v1/continue
+
+    ipappend 3
+
+  Replace ``{IP}`` with IP of the machine (do not use loopback interface, it
+  will be accessed by ramdisk on a booting machine).
+
+Use `ironic-discoverd element`_ as an example for this configuration.
+
+.. _diskimage-builder: https://github.com/openstack/diskimage-builder
+.. _discovery-ironic element: https://github.com/agroup/instack-undercloud/tree/master/elements/discovery-ironic
+.. _ironic-discoverd element: https://github.com/agroup/instack-undercloud/tree/master/elements/ironic-discoverd
+
+Running
+~~~~~~~
+
+Run as ``root``::
+
+    ironic-discoverd /etc/ironic-discoverd/discoverd.conf
+
+Developing
+~~~~~~~~~~
+
+Checkout and create an environment::
+
+    git clone https://github.com/Divius/ironic-discoverd.git
+    cd ironic-discoverd
+    make test_env
+
+Run test suite::
+
+    make test
+
+Install and run::
+
+    source .env/bin/activate
+    python setup.py develop
+    ironic-discoverd example.conf
+
+Of course you may have to modify ``example.conf`` to match your OpenStack
 environment.
 
 API
 ---
 
+By default *ironic-discoverd* listens on ``0.0.0.0:5050``, this can be changed
+in configuration. Protocol is JSON over HTTP;
+
 HTTP API consist of 2 endpoints:
 
-* ``/v1/discover`` initiate hardware discovery. Request body: JSON - list of
-  UUID's of nodes to discover. All power management configuration for these nodes
-  needs to be done prior to calling the endpoint. Requires X-Auth-Token header
-  with Keystone token for authentication.
+* ``POST /v1/discover`` initiate hardware discovery. Request body: JSON - list
+  of UUID's of nodes to discover. All power management configuration for these
+  nodes needs to be done prior to calling the endpoint. Requires X-Auth-Token
+  header with Keystone token for authentication.
 
   .. note::
       Before version 0.2.0 this endpoint was not authenticated.
       Now it is, but check for admin role is not implemented yet.
 
-* ``/v1/continue`` internal endpoint for the discovery ramdisk to post back
-  discovered data. Should not be used for anything other than implementing
+  Response: always HTTP 202.
+
+* ``POST /v1/continue`` internal endpoint for the discovery ramdisk to post
+  back discovered data. Should not be used for anything other than implementing
   the ramdisk. Request body: JSON dictionary with keys:
 
   * ``cpus`` number of CPU
@@ -56,3 +122,26 @@ HTTP API consist of 2 endpoints:
   * ``memory_mb`` RAM in MiB
   * ``local_gb`` hard drive size in GiB
   * ``macs`` list of MAC addresses for all NIC's
+
+  Response: always HTTP 202.
+
+ChangeLog
+---------
+
+v0.2.0
+~~~~~~
+
+* Authentication via Keystone.
+* Switch to setuptools entry points.
+* Enhanced documentation.
+
+v0.1.1
+~~~~~~
+
+* Added simple man page.
+* Make interface configurable.
+
+v0.1.0
+~~~~~~
+
+* First stable release.