update doc sections with some introductory text and add a few examples