updates of documentation - this commit has some bugs that are mentioned in (new) issues - starting from #16
