diff --git a/docs/README.md b/docs/README.md
index cdcf023fd5..7a5ee3f8a9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,27 +1,42 @@
-docker website
-==============
+Docker documentation and website
+================================
 
-This is the docker website repository
+Documentation
+-------------
+This is your definite place to contribute to the docker documentation. The documentation is generated from the
+.rst files under sources.
 
-installation
+The folder also contains the other files to create the http://docker.io website, but you can generally ignore
+most of those.
+
+
+Installation
 ------------
-* Checkout this repo to your local dir
-* Install sphinx: ``pip install sphinx``
-* Push this to dotcloud
 
+* Work in your own fork of the code, we accept pull requests.
+* Install sphinx: ``pip install sphinx``
+* If pip is not available you can probably install it using your favorite package manager as **python-pip**
 
 Usage
 -----
-* run make docs
-* your static website can now be found in the _build dir
 * change the .rst files with your favorite editor to your liking
-* run *make clean* to clean up
-* run *make docs* to build the new version
+* run *make docs* to clean up old files and generate new ones
+* your static website can now be found in the _build dir
+* to preview what you have generated, cd into _build/html and then run 'python -m SimpleHTTPServer 8000'
+
+Working using github's file editor
+----------------------------------
+Alternatively, for small changes and typo's you might want to use github's built in file editor. It allows
+you to preview your changes right online. Just be carefull not to create many commits.
+
+Images
+------
+When you need to add images, try to make them as small as possible (e.g. as gif).
 
 
 Notes
 -----
-* The index.html file is copied from the source dir to the output dir without modification. So changes to
- the index.html page should be made directly in html
-* a simple way to run locally. cd into _build and then run 'python -m SimpleHTTPServer 8000'
-* For the Template the css is compiled from less. When changes are needed they can be compiled using lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
\ No newline at end of file
+* The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.
+So changes to those pages should be made directly in html
+* For the template the css is compiled from less. When changes are needed they can be compiled using
+lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
\ No newline at end of file