diff --git a/README.md b/README.md
deleted file mode 100644
index 928ceee4..00000000
--- a/README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-TaskFlow
-========
-
-A library to do [jobs, tasks, flows] in a HA manner using different backends to
-be used with OpenStack projects.
-
-* More information at http://wiki.openstack.org/wiki/TaskFlow
-
-Join us
--------
-
-- http://launchpad.net/taskflow
-
-Testing and requirements
-------------------------
-
-### Requirements
-
-Because TaskFlow has many optional (pluggable) parts like persistence
-backends and engines, we decided to split our requirements into two
-parts:
-- things that are absolutely required by TaskFlow (you can't use
-  TaskFlow without them) are put to `requirements.txt`;
-- things that are required by some optional part of TaskFlow (you
-  can use TaskFlow without them) are put to `optional-requirements.txt`;
-  if you want to use the feature in question, you should add that
-  requirements to your project or environment;
-- as usual, things that required only for running tests are put
-  to `test-requirements.txt`.
-
-### Tox.ini
-
-Our tox.ini describes several test environments that allow to test
-TaskFlow with different python versions and sets of requirements
-installed.
-
-To generate tox.ini, use the `toxgen.py` script by first installing
-[toxgen](https://pypi.python.org/pypi/toxgen/) and then provide that script
-as input the `tox-tmpl.ini` file to generate the final `tox.ini` file.
-
-*For example:*
-
-    $ toxgen.py -i tox-tmpl.ini -o tox.ini
-
-
-Documentation
--------------
-
-http://wiki.openstack.org/wiki/TaskFlow
-
-We also have sphinx documentation in `docs/source`. To build it,
-run:
-
-    $ python ./setup.py build_sphinx
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..f16b9688
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,59 @@
+TaskFlow
+========
+
+A library to do [jobs, tasks, flows] in a highly available, easy to understand
+and declarative manner (and more!) to be used with OpenStack and other
+projects.
+
+- More information can be found by referring to the `developer documentation`_.
+
+Join us
+-------
+
+- http://launchpad.net/taskflow
+
+Testing and requirements
+------------------------
+
+Requirements
+~~~~~~~~~~~~
+
+Because TaskFlow has many optional (pluggable) parts like persistence
+backends and engines, we decided to split our requirements into two
+parts: - things that are absolutely required by TaskFlow (you can’t use
+TaskFlow without them) are put to ``requirements.txt``; - things that
+are required by some optional part of TaskFlow (you can use TaskFlow
+without them) are put to ``optional-requirements.txt``; if you want to
+use the feature in question, you should add that requirements to your
+project or environment; - as usual, things that required only for
+running tests are put to ``test-requirements.txt``.
+
+Tox.ini
+~~~~~~~
+
+Our ``tox.ini`` file describes several test environments that allow to test
+TaskFlow with different python versions and sets of requirements installed.
+
+To generate the ``tox.ini`` file, use the ``toxgen.py`` script by first
+installing `toxgen`_ and then provide that script as input the ``tox-tmpl.ini``
+file to generate the final ``tox.ini`` file.
+
+*For example:*
+
+::
+
+    $ toxgen.py -i tox-tmpl.ini -o tox.ini
+
+Developer documentation
+-----------------------
+
+We also have sphinx documentation in ``docs/source``.
+
+*To build it, run:*
+
+::
+
+    $ python setup.py build_sphinx
+
+.. _toxgen: https://pypi.python.org/pypi/toxgen/
+.. _developer documentation: http://docs.openstack.org/developer/taskflow/
diff --git a/setup.cfg b/setup.cfg
index bc8f9a32..0c396204 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,7 +2,7 @@
 name = taskflow
 summary = Taskflow structured state management library.
 description-file =
-    README.md
+    README.rst
 author = Taskflow Developers
 author-email = taskflow-dev@lists.launchpad.net
 home-page = https://launchpad.net/taskflow