added comments from discussion about diagrams