some additions to the documentation (work in progress)