I have a comment that (in my opinion) fits in this thread.
I would like to see a good way of pointing out new imapd.conf options.
Now you have to look at bug reports, changelog, install-upgrade to find
Sometimes they are not documented even, but that is a different problem.
Regarding install-upgrade.html, I think that this file is not read by
default by most sysadmins. E.g. I just look in the changelog. If it
mentions install-upgrade.html I go look at it.
(Unless I know there are big changes.)