changes to documentation covering Issue 2