I like to think I know the MusicBrainz relationship system and UI pretty well, but I was confused by some of the messages it gave me recently, when I tried to apply a Mastering relationship to a Release. I think that clearer documentation would help.
I was applying Relationships to a Release, describing orchestra performance, conductor, recording place, recording engineer, mixing engineer, and mastering engineer. Of course, all of these should be applied to the Recording, not the Release, I thought. The MusicBrainz web UI has a very convenient way of selecting all tracks, then specifying Relationships one after the other. I added "orchestra", "conductor", etc., etc.. No problem until "mastering engineer". When I specified an Artist with a "Mastering" relationahip, I saw a warning message in the pop-up Relationship dialogue: "This relationship type is deprecated and should not be used."
I didn't understand why the "Mastering" Relationship would be deprecated. I searched the MB documentation, and there is a Mastering Relationship page which says nothing about deprecation. I was confused.
Wait, "all of these should be applied to the Recording, not the Release"? Not quite all! The Mastering credit should be applied at the Release level, not the Recording level. The documentation for Relationship Types / Artist-Recording / Mastering does indeed say "This relationship type is deprecated! Please add mastering engineers at the release level."
So, what caused my confusion? What could be improved?
I think the error message that appears in the Relationship creation dialogue, "This relationship type is deprecated and should not be used", is incomplete in that context. Better wording would be, "Mastering realationships should be applied to Release. Applying to Recording is deprecated".
What does it take to implement such a wording change?
It would help if there was some text in all the "Mastering" Relationship Type pages which explained when to use the various entity variations of "Mastering":
Maybe the text could be something like:
The Mastering relationship gives credit for the task of ''mastering'', that is, preparing "the audio source from which all copies will then be manufactured". This credit is release level, so therefore, apply it at the Release level, using the Artist-Release / Mastering Relationship Type. Credit at the Recording (track) level is deprecated, though some Recordings still have old Artist-Recording / Mastering Relationship Types. There is also a Artist-Place / Mastering engineer position Relationship Type. It is to indicate that a mastering engineer works at a certain studio.
Related to this, I think the MusicBrainz documentation isn't completely clear about whether the term "Relationship" refers to the relating concept and all variations of entity type, or to just one combination of relating concept and entity type. For instance, does the term "Mastering Relationship" refer to all three entity combinations above (Artist-Release, Artist-Recording, and Artist-Place), or are those three independent "Relationships"? My mental model has been the former. I don't think the documentation page "Relationships" really talks about this difference, or adopts one model or the other.
If discussion here reveals a consensus about which model to adopt, I can draft text for the documentation page accordingly.
The Style / Relationships guideline talks about preferring credit at the track rather than the Release level, but it doesn't talk about the case of Mastering, which is the reverse.
I decided to be bold, in the Wikipedia tradition, and add clarification about Mastering credit to that wiki page. Style and Documentation leaders, please review.