WikiDocs: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
mNo edit summary
(Replacing mention of "wiki web service" and replacing it with "transclusion mechanism".)
Line 11: Line 11:
Thus, it is vitally important for the wiki to be open for anyone to edit.
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 [[Frequently Asked Questions|FAQs]] and the [[Official Style Guideline|style guidelines]]) warrant an 'official' status. There are also other pages that are integrated into the main site (such as [[Products|product]], [[Development|development]], and [[MusicBrainz License|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.
Leaving the wiki open anyone to edit has its inconveniences though. There are various pages that have had their content carefully written and reviewed by the MusicBrainz user community (such as the [[Frequently Asked Questions|FAQs]] and [[Official Style Guideline|style guidelines]]) and so they warrant some sort of 'official' status. There are also other pages that are integrated into the main site (such as [[Products|product]], [[Development|development]], and [[MusicBrainz License|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:
A "WikiDocs" system was introduced that accounted for the above by:
# Leaving the wiki open for mass collaboration on http://wiki.musicbrainz.org/.
# Leaving the wiki open for mass collaboration on http://wiki.musicbrainz.org/.
# Providing [[Transclusion Editor|transclusion editors]] with the means to control what is viewable on http://musicbrainz.org/doc/.
# Providing [[Transclusion Editor|transclusion editors]] with the means to control what is viewable on http://musicbrainz.org/doc/.
Line 22: Line 22:


The structure of the WikiDocs system looks like this:
The structure of the WikiDocs system looks like this:
# All content resides in the [[MusicBrainz Wiki]].
# All the content resides in the [[MusicBrainz Wiki]].
# [[Transclusion Editor|Transclusion editors]] add/maintain entries on the [http://musicbrainz.org/edit/wikitransclusion/transclusion.html transclusion table] for pages that require controlled transclusion.
# [[Transclusion Editor|Transclusion editors]] add and maintain entries in the [http://musicbrainz.org/edit/wikitransclusion/transclusion.html transclusion table] for all official documentation pages.
# 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.
# Users visiting the MusicBrainz Wiki see no difference; they always see the most recent revision of every page, and are able to edit any page.
# Users visiting the MusicBrainz website will be served content from the wiki via the [[Wiki Web Service|wiki web service]] which checks to see if the page being requested exists in the transclusion table.
# Users visiting the MusicBrainz website will be served content from the wiki via the transclusion mechanism.
#* If it does, the web service will fetch the page using the revision number listed on the table, pass it through the [[WikiDocs Conversion|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|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.
The pages served by the transclusion mechanism are not editable on the website, but they provide a link back to their corresponding page on the wiki.

== Transclusion Mechanism ==

The transclusion mechanism is the magic behind the entire WikiDocs concept and it kicks in when a user visits a page on http://musicbrainz.org/doc/.

First, the transclusion mechanism checks to see if the page being requested exists in the transclusion table.

If it does:
# The page is fetched using the revision number listed on the table.
# The footer states, "This WikiDocs Page is based on revision <code><revision number></code> of <code><page name></code>".
If it doesn't:
# The current revision of the wiki page is fetched.
# A warning is added to the top of the page that states, "This page has not been reviewed by our documentation team".
# The footer states, "This WikiDocs Page is a copy of <code><page name></code>".

In both cases, the page is passed through a conversion process that bolds links to other official documentation pages.


[[Category:Wiki]] [[Category:WikiDocs Page]]
[[Category:Wiki]] [[Category:WikiDocs Page]]

Revision as of 04:11, 25 October 2009

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 and reviewed by the MusicBrainz user community (such as the FAQs and style guidelines) and so they warrant some sort of '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.

A "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 the content resides in the MusicBrainz Wiki.
  2. Transclusion editors add and maintain entries in the transclusion table for all official documentation pages.
  3. Users visiting the MusicBrainz Wiki see no difference; they always see the most recent revision of every page, and are able to edit any page.
  4. Users visiting the MusicBrainz website will be served content from the wiki via the transclusion mechanism.

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

Transclusion Mechanism

The transclusion mechanism is the magic behind the entire WikiDocs concept and it kicks in when a user visits a page on http://musicbrainz.org/doc/.

First, the transclusion mechanism checks to see if the page being requested exists in the transclusion table.

If it does:

  1. The page is fetched using the revision number listed on the table.
  2. The footer states, "This WikiDocs Page is based on revision <revision number> of <page name>".

If it doesn't:

  1. The current revision of the wiki page is fetched.
  2. A warning is added to the top of the page that states, "This page has not been reviewed by our documentation team".
  3. The footer states, "This WikiDocs Page is a copy of <page name>".

In both cases, the page is passed through a conversion process that bolds links to other official documentation pages.

Retrieved from "https://wiki.musicbrainz.org/index.php?title=WikiDocs&oldid=31915"