update the descriptions
guide will continue to evolve
fix links