some updates to the docs in line with recent updates