new docs

this didn't get completed but it's a start, anyone else got time to contribute to this branch? I'm happy to give access to my fork to whoever wants to contribute to docs before it's merged.