Reapplying matzew changes

Due to my bad PR merge without rebase as discussed here:
http://aerogear-dev.1069024.n5.nabble.com/aerogear-dev-Lost-commits-merges-td5243.html

I could not find original commit with SHA-1 5ec383f35a1346e2041e2c05b5273764ebf444ea

So I manually (carefully) reapply the documentation changes.

Please review and I'll merge it.