Update docs

@jpihl @petya2164 @jepkri @jledet 

Open for code review :)
with can will => which will