WikiDocs

From MusicBrainz Wiki
Revision as of 02:30, 25 October 2009 by Nikki (talk | contribs)

WikiDocs Concept

With a few exceptions, the MusicBrainz Wiki is the source of all MusicBrainz' documentation.

This is achieved by transcluding all the content from http://wiki.musicbrainz.org/ to http://musicbrainz.org/doc/.

The Wiki and WikiDocs

The MusicBrainz Wiki is seen as the community responsible for generating all the documentation, help pages, and guidelines for MusicBrainz. The wiki community has been very efficient in doing this because both the experts (the solution providers) and the non-experts (the question posers) collaborate in the same space.

Thus, it is vitally important for the wiki to be open for anyone to edit.

Leaving the wiki open anyone to edit has its inconveniences though. There are various pages that have had their content carefully written by the consensus of the MusicBrainz user community (such as the FAQs and the style guidelines) warrant an 'official' status. There are also other pages that are integrated into the main site (such as product, development, and licensing pages) that provide visitors and new users their first impressions of MusicBrainz. The damage an editor on the wiki can do, whether maliciously or just by accident, is quite extensive.

Therefore the WikiDocs system was introduced that accounted for the above by:

  1. Leaving the wiki open for mass collaboration on http://wiki.musicbrainz.org/.
  2. Providing transclusion editors with the means to control what is viewable on http://musicbrainz.org/doc/.

WikiDocs Structure

WikiDocs components

The structure of the WikiDocs system looks like this:

  1. All content resides in the MusicBrainz Wiki.
  2. Transclusion editors add/maintain entries on the transclusion table for pages that require controlled transclusion.
  3. Users visiting the MusicBrainz Wiki see no difference. They always see the most recent revision of every page, and will always be able to edit any page.
  4. Users visiting the MusicBrainz website will be served content from the wiki via the wiki web service which checks to see if the page being requested exists in the transclusion table.
    • If it does, the web service will fetch the page using the revision number listed on the table, pass it through the WikiDocs conversion process, and finally serve it.
    • If it doesn't, the web service fetches the current revision of the wiki page and passes it through the WikiDocs conversion process, which, among other things, adds a warning that the page "has not been reviewed by our documentation team" before it's served.

The pages served by the web service are not editable on the website, but they all provide a link back to their corresponding page on the wiki.