updates to docs from @dirk-thomas's comments and fill in somre more details.