BZ-1038214: adding documentation
(cherry picked from commit fd4d5b64ce172a9e562c65e33f02f89044c9a088)
another big round of edits
(cherry picked from commit ee61b60cd86b5b217efa4571ecf9c3abb20dbe5d)