Thank you for your tact! Producing documentation can indeed sometimes feel a somewhat thankless task, but it is useful to have feedback since, as I’m sure you’ll appreciate, it isn’t always obvious to the documentation author what other people will make of what he or she writes.
I can see the value of cross-referencing, but I don’t want to put in too much duplication of material that’s already covered elsewhere. To that end I’ve added a paragraph to the end of the “Messages” section of the Messages chapter that reads:
First, though, it’s worth emphasising that the DMsg() and BMsg() mechanisms are primarily intended for library messages, i.e. messages that the library uses to provide a default response (such as “Taken” or “You can’t attach the widget to anything”) when a game author hasn’t provided a more specific response. There may be occasions when game authors want to customize these default messages, so it’s useful to know how these mechanisms work, but note that this isn’t the way you’d normally go about customizing specific responses on specific objects (such as “You gingerly pick up the vase” or “The cheese smells exceptionally ripe”). For that kind of thing you’d typically just override an appropriate message property (or method) with your own string (e.g. smellDesc = "The cheese smells exceptionally ripe. "), using, for example, one of the properties provided for the purpose on the Thing class or one of the methods described in the discussion of Action Results.