Improve documentation on versioning scheme

Fixes #1887