documentation: merge & adapt suggestions from baus