fix (docs): cosmetics (#45)

docs/index.md

@@ -15,7 +15,7 @@ The package consists of:
     - dump an existing ontology from a DSP server to a JSON file
     - Bulk-upload of data from a XML data file
 
-## Install
+# Install
 
 To install the latest version published on PyPI run:
 ```
@@ -27,6 +27,15 @@ To update to the latest version run:
 $ pip3 install --upgrade dsp-tools
 ```
 
+# Developer
+
+## Makefile
+
+There is a helping `Makefile` for all of the following tasks (and more).  
+It is self-explanatory and a simple `make` will print its available targets.
+
+## Install from source
+
 To install from source, i.e. this repository run:
 ```
 $ python3 setup.py install
@@ -47,6 +56,14 @@ To generate a "requirements" file (usually requirements.txt), that you commit wi
 $ pip3 freeze > requirements.txt
 ```
 
+## Testing
+
+```bash
+$ pip3 install pytest
+$ pip3 install --editable .
+$ pytest
+```
+
 ## Publishing
 
 Generate distribution package. Make sure you have the latest versions of `setuptools` and `wheel` installed:
@@ -87,26 +104,19 @@ For local development:
 $ python3 setup.py develop
 ```
 
-## Testing
-
-```bash
-$ pip3 install pytest
-$ pip3 install --editable .
-$ pytest
-```
-
-## Requirements
+## Contributing to the documentation
 
-To install the requirements:
+The documentation is a collection of [markdown](https://en.wikipedia.org/wiki/Markdown) in the `docs` sub-folder.  
+After updates, it is possible to build and check the result with the commands:
 
 ```bash
-$ pip3 install -r requirements.txt
+$ make build-docs
+$ make serve-docs 
 ```
 
-
-To generate a "requirements" file (usually requirements.txt), that you commit with your project, do:
+To update the changes to the official documentation pages:
 
 ```bash
-$ pip3 freeze > requirements.txt
+$ make publish-docs
 ```