checked through docs, cleaning up examples and bringing them up to date
cleaned up discussion and conclusion