User:Kuno/styleguideline

From MusicBrainz Wiki
< User:Kuno
Revision as of 17:07, 26 October 2009 by 80.101.192.137 (talk)

Preamble

NOTE: This is an attempt to figure out how to structure the style guidelines (post NGS). It is written as a Table of Contents, the aim is to:

  • Give a recommended reading order for new users, following this TOC they should learn the basics of adding new releases by only reading the first few wiki pages linked to in this TOC.
  • Merge various smaller guidelines into larger, more coherent documents.
  • Seperate edge cases and exceptions from the core guidelines in such a way that (see also my notes further below):
    1. The core guideline stands out, and is easily understood and remembered.
    2. The edge cases don't get lost in a structureless mess where only guideline lawyers can find them.

The page titles used here are not final, but should give you some idea of what my aim is. Suggestions welcome ofcourse. Some conventions used:

text following a title gives a short summary of what the page linked to should contain.
text between 〜wave dashes〜 gives current official style guideline pages which can be merged into the page mentioned.

Roadmap

step 1. This document was written by kuno, aka warp. I am discussing these issues with other people on #musicbrainz-devel (DONE).

step 2. When we're happy with it, I plan to present it to the StyleCouncil, to discuss with a larger group of people.

step 3. When the StyleCouncil is happy with, we can start writing the actual guidelines. I just want to start at the beginning, and get these pages written one by one, at first just the guideline without any examples and edge cases. (though we can copy/paste examples and edge cases from the current guidelines where applicable).

step 4. The previous step should have resulted in a complete set of official guidelines. The only thing left in this final step is to add or trim examples and edge cases where needed. (which is just mb-style going back to doing what it always does :)


Proposed "post NGS styleguide" table of contents

Getting started

  1. Quickstart
    contains a summary of the guidelines, reminiscent of http://web.archive.org/web/20070106165630/http://musicbrainz.org/style.html .
  2. Style Principle
    〜I think we can merge in ConsistentOriginalData〜
  3. Adding a new release
    should be added last, when the guidelines are done, more below.

Detailed guidelines

  1. Titles
    Deals with the stuff that is common about Track, Release, Recording and Work titles.
    〜Should merge in MainTitle, SubTitle, MultipleTitle and SplitReleaseTitle, SeriesNumber〜
  2. Track
    〜Should merge in: TrackVersion, RemixStyle, ExtraTitleInformation, this should be possible by rewriting some bits and throwing away a bunch of examples〜
  3. Release title
    Deals with Box/Volume/Disc stuff
  4. Recording and Work title
    Probably very short guidelines for non-classical, these seem mostly useful for classical, so point there.
  5. Artist
    Deals with how to pick a name for the artist, LegalName, performance name, this can be based on the current ArtistName page, but with rewrites due to the changes of NGS, also links to PerformanceName and other relevant ARs. Also touch on gender, country, etc.. though these should be mostly self-explanatory and hardly mentioned in the guideline itself.
    nikki notes: "a lot of the current guidelines are aimed at not creating new artists, when that won't matter anymore, because we'll be able to link as many artists as we like".
  6. Unknown and Untitled
    This should really be called "Special Purpose", as this is the page which collects all the special purpose artists/labels/etc.. so they don't clutter up each of the other pages. I don't like a title which starts with "Special Purpose" though, it isn't clear to new users what is so special about them. So, we need a better title, "Unknown and Untitled" is better IMO, but doesn't fit all the things I would like to collect on this page. Suggestions welcome.
    〜merge in SpecialPurposeArtist, NoArtist, UnknownArtist, SpecialPurposeLabel, though perhaps we should keep artist and label separate〜
  7. Relationships
    Most relationships have enough information on the page which documents their use, and don't really need guidelines in addition to their regular documentation. The only things I can think of now are:
    1. the cover AR because I see a fair amount of edits which don't take into account that you're not allowed to link to certain things -- though perhaps it would be better to solve that on the server itself (don't allow links to be added we don't approve).
    2. other url links because they're a bit fuzzy.
  8. Specific types of releases
    1. Soundtrack
    2. Classical
    3. LiveBootleg
    4. ... anything else?

Language specific guidelines

I would prefer to move any language specific stuff to seperate pages, which will remove a bit of clutter from some of the regular guidelines, and makes it easier for someone who just starts working in a particular language to see clearly in what areas that language differs from our main guidelines.

  1. Dutch
    1. Capitalization standard
    2. Sortname
    3. anything else?
  2. German
    1. Capitalization standard
    2. Sortname
    3. ...
  3. French
    1. ...
    2. ...

post NGS styleguide "Adding a new release" page

NOTE: This should not be a guide on how to add a release. It is a tutorial on how to read and apply the guidelines when adding a typical (pop) release.

It should deal with the basics, possibly as a step by step instruction for a particular album which happens to touch a few interesting guidelines.

  • Release title (link to CapitalizationStandard)
  • Track titles (use an example which neccesitates linking to AbbreviationStyle or FeaturingArtistStyle, reiterate CapitalizationStandard)
  • Choosing / adding the artist (Point out the difference between the legal name and the artist name used on the release)
  • Quickly explain the remaining stuff (release type, language, label etc..)

Actually, the above probably contains too many links to other style guidelines, should decide which of those are important and which of them can wait... and write the most readable introduction to the subject. Or described two releases instead of one, introducing some interesting guidelines on the second example.

Probably mention that certain releases have different rules and conventions, linking to Classical/Soundtrack styles.


Seperate edge cases and exceptions from the core guideline

I want to have some way to clearly seperate a core guideline from the examples and edge cases. A bit similar to CC has a human readable and a proper legalese version of their licenses, although the seperation should not be that drastic.

I would like some help from our user interaction / graphic designer volunteers on how to improve the layout of the style pages. We don't have to limit ourselves to what we can do within wikipedia, I think we have some more control over the rendering of the transcluded versions. Perhaps we can get a consistent look & feel for each of the guidelines with some nice icons and bigger text for the proper guideline.

Another idea would be to have the example and edge cases sections collapsed on page load, with an easy way to expand them (nikki mentioned wiktionary doing this for translations).

To re-iterate why these changes are need, I want to achieve the following:

  1. The core guideline should stand out, must be easily understood and remembered.
  2. The edge cases shouldn't get lost in a structureless mess where only guideline lawyers can find them.