Update docs

@jpihl @petya2164 @jepkri @jledet 

Open for code review :)
manually inspecting