cleanup documentation, moving things from cmf doc here

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes
| Applies to    | 1.1
| Fixed tickets | #103