docs(upgrade-guide): editorial tweaks and fixes