Clarifications, added info on doc, format

@stroilova , @rocha , @mulby please take a look. I standardized the heading format as well as making very light edits base don today's converstation with Olga and Carlos.