update docs, after Lennart review