Documentation Release

Abstract

MusicBrainz documentation is based almost entirely on its wiki content. This is a big strength (as it lets any editor enhance it in a collaborative fashion), but it also has a number of heavy shortcomings:

• there is no clear delimitation between the (site) end-user documentation, and the "wild" wiki where long discussions, history and various propositions are intertwingled, making it rather indigest and intimidating for the newcomer
• the documentation suffers from severe quality, style, and synchronization discrepancies
• being the need to "lock" some content (on the MusicBrainz site side), we have a transclusion mechanism in place. Unfortunately, this mechanism is rather awkward and it's rather difficult for a handful of editors to maintain the transclusion table up to date for vastly heterogeneous contents

Objective

We plan on incrementally enhancing the documentation global quality and try address these shortcomings, by making "micro-releases" of it.

Ultimately (medium/long term?), the concept of documentation releases should be used to keep the documentation in synch with the site, and make global DocumentationReleases each time the site is updated.

Also, we would like to refine our concepts about documentation, and encourage the creation of a (constant) documentation effort through the constitution of a DocumentationTeam (topic which is related with the need for more TransclusionEditors if that mechanism is going to be massively used).

Difficulties

• no one actively worked on this, though the idea was in the air for almost one year (pretty much since the parallel emergence of the WikiWardening effort), and despite numerous rants about the low quality of the docs, including from rather "veteran" editors
• the task is huge
• such an effort requires editors to switch their routine focuses: usually, people are (just) motivated to defend their ideas, and write new content to promote them. They also have strong opinions about specific points (this is fair!), areas in which they feel they are specialists while disregarding the rest (fair also!), and tendency to favor the more refined/complicated areas (being the most interesting!), not to mention discussing about things is often favored over actually documenting them ;) . Actively working on the documentation on the other hand requires to rather focus on:
  • fairness about the various opinions on touchy topics
  • good global experience and global view of the project and wiki
  • non-tainted (eg: by a specific view on music) attitude
  • ability to present content in a simple enough manner while still retaining all relevant information
  • ability to just go over the usual styleML nitpicking about trivial details and purists views
  • capacity to take fire for all the (potentially bold) moves you'll be forced to make (you will break some eggs - and some people will be unhappy about what you will do - including private niceties and public slandering :-) )
  • desire to do very ungrateful maintenance work

Typically, this effort does not consist (essentially) in solving the various pending style issues with a brand shiny new (born-dead, most time) (possibly overkill) proposition, but rather address the problems pertaining to the way we document things.

Releases

The current target is version 1.0 (codenamed "Pass the Cheese, Baby" - and no, we don't need a wiki page by that name :-) ). It doesn't have to be perfect. It doesn't even have to be complete. The main purpose of it is rather to try and see if a new dynamic can be put into motion, and if we can put in place a usable and decent architecture through the use of cards. Also, eliminating the biggest zones of bit-roting and moving out the most invading discussions and history bits is one of its main objectives.

How to Help

Unfortunately, energy and time are too sparse to devote (yet - that is, for the 1.0 release) on a well defined "newcomer" what-to-do guide.

If you're a veteran WikiZen and are in the mood for it (see the "difficulties" section for a quick check), you know what to do (or you'll figure out quickly).

If you don't, you can still help! You may either mail one of the editors involved in this (check the contributors to the version 1.0 page) for a quick heads-up, or check directly version 1.0 and the pages already considered "decent" and try to make some sense out of it to figure out what needs to be done.

Notes

For additional ramblings about documentation, check this page.