tweaked documentation with better text and correct links