[MSHARED-628] improved documentation to describe separately current normal use and former new format which is now deprecated