update documentation

To be merged once the relevant code changes land.