Improve the documentation

Close #818 

WIP! Do not merge!