[WIP] cleaning up the odm documentation

| Q   | A
| --- | ---
| Doc fix? | yes
| New docs? | yes
| Applies to | dev
| Fixed tickets | #470 

still a couple of build errors but have to stop now. will continue tomorrow to fix linking errors and such.

but glad for content feedback. i did not write much new content, mostly split the content and removed some redundancy.