[throwaway984393]

Actually our tendency is to re-use the old solution on the new code if it provides the same functionality. We still have people trying to use LDAP because nobody wants to take the time to learn something new. A migration guide makes it much more likely that they'll make an attempt to use the new thing.

Our desire to upgrade pretty much only comes from Architects telling us "thou shalt follow my shiny new standard" (and by the way, they read your docs; if you suggest SAML be dropped, they'll update their standards!). In that case we have to find time to upgrade, and of course we never just document how to do it once for our whole org, so all these engineers will be wasting time re-learning how to do the same upgrade. I'll bet you we'd save hundreds to thousands of hours per year by having really good migration docs. Even if your migration guide doesn't cover everything, they still take a significant chunk out of the time we need to figure it all out, and it lowers the mental barrier to the change.