update docs, after Lennart review
Merge pull request #628 from georgebyelas/master

update docs, after Lennart review