[Docs] README update

docs/README.md

@@ -18,14 +18,21 @@ The documentation uses [GitHub issues](https://github.com/Sylius/Sylius/issues).
 Build
 -----
 
-If you contribute to documentation you will want to check how it looks after your changes.  
-To be able to build the documentation, install [Sphinx](http://sphinx-doc.org/).
+To test the documentation before a commit:
 
-1. [Install `pip`, Python package manager](https://pip.pypa.io/en/stable/installing/)
-2. Download documentation requirements: `$ pip install -r requirements.txt`
-3. Build the documentation:`$ sphinx-build -b html . build`
+* [Install `pip`, Python package manager](https://pip.pypa.io/en/stable/installing/)
 
-Documentation index is `build/index.html`.
+* Download the documentation requirements: 
+
+    `$ pip install -r requirements.txt`
+    
+    This makes sure that the version of Sphinx you'll get is >=1.4.2!
+
+* Install [Sphinx](http://www.sphinx-doc.org/en/stable/)
+
+    `$ pip install Sphinx`
+
+* In the `docs` directory run `$ sphinx-build -b html . build` and view the generated HTML files in the `build` directory.
 
 Authors
 -------

docs/contributing/documentation/overview.rst

@@ -54,25 +54,23 @@ Testing Documentation
 
 To test the documentation before a commit:
 
-* Install `Python`_
+* Install `pip`_, the Python package manager,
+
+* Download the documentation requirements,
 
 .. code-block:: bash
 
-    $ brew install python
+    $ pip install -r requirements.txt
+    # This makes sure that the version of Sphinx you'll get is >=1.4.2!
 
-* Install `Sphinx`_
+* Install `Sphinx`_,
 
 .. code-block:: bash
 
-    $ sudo pip install Sphinx
-
-.. note::
-
-    Please, make sure that the version of `Sphinx`_ you've got is >=1.4.2!
+    $ pip install Sphinx
 
 * In the ``docs`` directory run ``sphinx-build -b html . build`` and view the generated HTML files in the ``build`` directory.
 
-
 Creating a Pull Request
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -140,6 +138,6 @@ Steps:
 
 .. _`fork`:                       https://help.github.com/articles/fork-a-repo
 .. _`pull requests`:              https://help.github.com/articles/using-pull-requests
-.. _`Python`:                     https://www.python.org/
+.. _`pip`:                        https://pip.pypa.io/en/stable/installing/
 .. _`Sphinx`:                     http://www.sphinx-doc.org/en/stable/
 .. _`Github tracker`:             https://github.com/Sylius/Sylius/issues/new