Difference between revisions of "WikiDocs"

From MusicBrainz Wiki
(Replacing mention of "wiki web service" and replacing it with "transclusion mechanism".)
(use interwiki prefixes)
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== WikiDocs Concept ==
+
With a few exceptions, all of MusicBrainz' documentation is obtained by transcluding content from http://wiki.musicbrainz.org/ and displaying it at http://musicbrainz.org/doc/.
  
With a few exceptions, the [[MusicBrainz Wiki]] is the source of all MusicBrainz' documentation.
+
This "WikiDocs" system works by:
 
+
# Leaving the wiki (and by extension, the documentation) open for mass collaboration.
This is achieved by transcluding all the content from http://wiki.musicbrainz.org/ to http://musicbrainz.org/doc/.
+
# Providing [[Transclusion Editor|transclusion editors]] with the means to control what is viewable on the main site.
 
 
== 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 [[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.
 
 
 
A "WikiDocs" system was introduced that accounted for the above by:
 
# 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/.
 
  
 
== WikiDocs Structure ==
 
== WikiDocs Structure ==
  
[[Image:WikiDocs_System_v1.png|thumb|350px|right|WikiDocs components]]  
+
{| class="wikitable" style="float: right; margin: 0 0 10px 10px"
 +
| [[Image:WikiDocs_System_v1.png|350px|WikiDocs components]]  
 +
|}
  
 
The structure of the WikiDocs system looks like this:
 
The structure of the WikiDocs system looks like this:
# All the content resides in the [[MusicBrainz Wiki]].  
+
# All the content resides in the wiki and is open for anyone and everyone to edit and maintain.
# [[Transclusion Editor|Transclusion editors]] add and maintain entries in the [http://musicbrainz.org/edit/wikitransclusion/transclusion.html transclusion table] for all official documentation pages.
+
# [[Transclusion Editor]]s add and update entries in the [[mb:admin/wikidoc|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 are able to edit any page.
+
# Users visiting a page on the wiki see no difference; they always see the most recent revision of every page.
# Users visiting the MusicBrainz website will be served content from the wiki via the transclusion mechanism.
+
# Users visiting that same page on the main website will be shown, via transclusion, only the latest reviewed revision of that page
  
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.
+
Pages served via transclusion are not editable on the website.
  
== Transclusion Mechanism ==
+
==How To Transclude a WikiDocs Page==
  
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/.
+
'''Only transclusion editors are able to do this.'''
  
First, the transclusion mechanism checks to see if the page being requested exists in the transclusion table.
+
: [[Image:Attention.png]] ''Please be very careful to enter the correct page name and revision number, they are '''not''' checked for correctness.''
  
If it does:
+
Go to the [[mb:admin/wikidoc|wiki transclusion table]]. Each page will have its own row which can be edited or removed; new ones can also be added. When a [[WikiDocs]] page has been edited, and the change conforms with the style guidelines and other social aspects -  and most importantly, makes the documentation better - the change should be reflected on the main server. To do this, find the latest revision number using the page history and update it in the transclusion table.  
# 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.
+
When adding a new page to the table, make sure to add it to the [[:Category:WikiDocs Page|WikiDocs page]] category.
  
 
[[Category:Wiki]] [[Category:WikiDocs Page]]
 
[[Category:Wiki]] [[Category:WikiDocs Page]]

Latest revision as of 23:00, 30 April 2014

With a few exceptions, all of MusicBrainz' documentation is obtained by transcluding content from http://wiki.musicbrainz.org/ and displaying it at http://musicbrainz.org/doc/.

This "WikiDocs" system works by:

  1. Leaving the wiki (and by extension, the documentation) open for mass collaboration.
  2. Providing transclusion editors with the means to control what is viewable on the main site.

WikiDocs Structure

WikiDocs components

The structure of the WikiDocs system looks like this:

  1. All the content resides in the wiki and is open for anyone and everyone to edit and maintain.
  2. Transclusion Editors add and update entries in the transclusion table for all official documentation pages.
  3. Users visiting a page on the wiki see no difference; they always see the most recent revision of every page.
  4. Users visiting that same page on the main website will be shown, via transclusion, only the latest reviewed revision of that page

Pages served via transclusion are not editable on the website.

How To Transclude a WikiDocs Page

Only transclusion editors are able to do this.

Attention.png Please be very careful to enter the correct page name and revision number, they are not checked for correctness.

Go to the wiki transclusion table. Each page will have its own row which can be edited or removed; new ones can also be added. When a WikiDocs page has been edited, and the change conforms with the style guidelines and other social aspects - and most importantly, makes the documentation better - the change should be reflected on the main server. To do this, find the latest revision number using the page history and update it in the transclusion table.

When adding a new page to the table, make sure to add it to the WikiDocs page category.