Improvements to the search upgrade docs

Various improvements to the search upgrade docs.  I made many smaller commits so that it's easier to dissect my changes.