some work on the user guide
small improvements
more docs polishing