[mb-style] [Clean up CSG] Documentation

[Jim DeLaHunt]

Brian:


Brian Schweitzer wrote:
> 
> So I can start getting the new CSG documentation in order, so as to
> prepare for the eventual RFP, would everyone please take a look at the
> rewritten CSG I mentioned earlier,
> http://wiki.musicbrainz.org/BrianFreud/sandbox , *ignoring* content
> for the moment, only paying attention to the structure and style of
> the document? ...
> 

Wow, this is a monumental bit of writing!

I think there is good material there, but I think it is too much to deliver
it in one article.  

My target audience for the CSG is a contributor who has a CD in one hand and
a MB web page in the other, who wants to get the music on the CD registered
in the database quickly and then move on to something else. They don't want
to absorb the full richness of the CSG for it's own sake.  Thus we need to
give the information in a form and sequence that lets them complete the data
entry task quickly but correctly.

I believe there is one CSG for all languages.  Rules like whether CSG
applies, and that Track Artist is set to composer not performer, and that
the Track Title identifies the work instead of the title printed on the
Release packaging, apply across languages.  The human language used only
affects some details of how the ReleaseTitle and TrackTitle are worded and
punctuated, it does not become a completely different CSG.  Thus I support
e.g. pages on FrenchTrackTitleIssues and EnglishTrackTitleIssues within one
CSG, not a FrenchCSG and an EnglishCSG.

I believe that the basic structure of documents should be:

1. ClassicalStyleGuide: entry point. Aimed at a contributor who wants to
complete a data entry task. Tells the 20% of the rules which apply to 80% of
the cases. Rarely explains "why", instead it refers to subarticles that
explain rationale, history, and details. Tells how to decide if CSG applies.
Summarises but delegates on to subarticles:
* ClassicalReleaseArtistStyle: how to set ReleaseArtist field correctly
* ClassicalReleaseTitleStyle: how to set ReleaseTitle field correctly
* ClassicalTrackTitleStyle: how to set TrackTitle field correctly
* ClassicalARStyle: how to set AdvancedRelationships correctly

2. ClassicalReleaseArtistStyle: Aimed at a contributor who wants to fill in
a ReleaseArtist field, and needs to decide between composer, Various
Artists, performing artist, or collaboration artist of performers. If this
gets lengthy, it supplies 20% of the information which covers 80% of the
cases and refers off to reference articles for the rest. Rationales, history
are removed to reference articles.

3. ClassicalReleaseTitleStyle: Aimed at a contributor who wants to fill in a
ReleaseTitle field, and didn't get enough guidance from the brief summary in
CSG article. If this gets lengthy, it supplies 20% of the information which
covers 80% of the cases and refers off to reference articles for the rest.
Rationales, history are removed to reference articles.

4. ClassicalTrackTitleStyle: Aimed at a contributor who wants to fill in a
ReleaseTitle field correctly. Contributor should be able to read this
article, and perhaps one referenced article for details of a less common
structure, and complete the task.  This will be the most complex article. It
supplies 20% of the information which covers 80% of the cases, and/or gives
a decision tree and refers to reference articles for less-common but complex
cases.  This is the article which links off to the works catalogues for
composers. 

5. ClassicalARStyle: Aimed at a contributor who wants to complete a data
entry task, and motivates them to add a few AdvancedRelationships which do
the most to improve the database.  Tells which ARs are the "must haves",
which are "nice to have" (rest are by implication not important). If this
gets lengthy, it supplies 20% of the information which covers 80% of the
cases and refers off to reference articles for the rest. Rationales, history
are removed to reference articles.

6. Reference articles: aimed at an advanced MB contributor or CSG maven who
wants to know the details, the whys, the rationale.  Can be long and
complete. Articles 1-5 link to these articles as necessary.


I think the draft you have in Sandbox tries to be all of #1-6, which is why
it is too long. 

A key filter for #1-5 is: does a particular bit of content help an impatient
editor get the data entry task done?  If not, then consider moving it off to
a reference article (#6).

Would it help if I made my own sandbox to demonstrate what I mean by this
structure?  I don't think I'll be able to do it by this weekend.  Thus I
think this weekend is too soon for a whole new CSG to go out for RFC.


-----
     -- http://jdlh.com/ Jim DeLaHunt , Vancouver, Canada  • 
http://wiki.musicbrainz.org/JimDeLaHunt

-- 
View this message in context: http://www.nabble.com/-Clean-up-CSG--Documentation-tp15450322s2885p15488246.html
Sent from the Musicbrainz - Style mailing list archive at Nabble.com.