Difference between revisions of "WikiDocs"

From MusicBrainz Wiki
(updated progress a bit (Imported from MoinMoin))
(use interwiki prefixes)
 
(41 intermediate revisions by 16 users not shown)
Line 1: Line 1:
=Basing the Documentation on the Wiki=
+
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/.
  
[[Image:Alert.png]] '''Warning''' the pages on WikiDocs are currently in transition.  
+
This "WikiDocs" system works by:
 +
# Leaving the wiki (and by extension, the documentation) open for mass collaboration.
 +
# Providing [[Transclusion Editor|transclusion editors]] with the means to control what is viewable on the main site.
  
This is [[Current Work|CurrentWork]].
+
== WikiDocs Structure ==
  
We want to base more of the main site's content on the very good documentation that has evolved in this wiki.  
+
{| class="wikitable" style="float: right; margin: 0 0 10px 10px"
 +
| [[Image:WikiDocs_System_v1.png|350px|WikiDocs components]]
 +
|}
  
==WikiDocsConcept==
+
The structure of the WikiDocs system looks like this:
 +
# All the content resides in the wiki and is open for anyone and everyone to edit and maintain.
 +
# [[Transclusion Editor]]s add and update entries in the [[mb:admin/wikidoc|transclusion table]] for all official documentation pages.
 +
# Users visiting a page on the wiki see no difference; they always see the most recent revision of every page.
 +
# Users visiting that same page on the main website will be shown, via transclusion, only the latest reviewed revision of that page
  
The main idea of the WikiDocs is that there will be ''no separate documentation''. ''All'' docs will be in the [[MusicBrainz Wiki|MusicBrainzWiki]]. Think of it like an open source project with a development and a stable release: The wiki markup text and the versions stored in the wiki are like the source code in CVS. The wiki as rendered by the wiki engine is like the development release, it contains the bleeding edge ideas, docs, discussions etc. This is good but confusing for new users. Thus we make something like a stable release of the wiki which consists of a structured portal to a moderated mirror of the wiki. See [[WikiDocs Concept|WikiDocsConcept]] for more details.  
+
Pages served via transclusion are not editable on the website.
  
===The components of the WikiDocs===
+
==How To Transclude a WikiDocs Page==
  
====Current Model====
+
'''Only transclusion editors are able to do this.'''
  
* All content will reside in the [[MusicBrainz Wiki|MusicBrainzWiki]]. The [[Wiki Migration|WikiMigration]] to [[Moin Moin|MoinMoin]] was an essential precondition.
+
: [[Image:Attention.png]] ''Please be very careful to enter the correct page name and revision number, they are '''not''' checked for correctness.''
* [[Wiki Docs Moderators|WikiDocsModerators]] select important wiki pages and register their last stable revision as [[Moderated Revision|ModeratedRevision]] in the [[Moderated Revision Table|ModeratedRevisionTable]].
 
* Users visiting the [[MusicBrainz Wiki|MusicBrainzWiki]] will see no difference.
 
* Users visiting the [[Main Site|MainSite]] will be served content from the [[Moderated Revision|ModeratedRevision]] of moderated wiki pages via the [[Wiki Web Service|WikiWebService]]. If there is no [[Moderated Revision|ModeratedRevision]], the webservice serves the content of the normal wiki page, but with a warning that this is unmoderated content. The pages served by the webservice will not be editable.  
 
  
====Initial idea====
+
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 [[MusicBrainz Wiki|MusicBrainzWiki]] (which will be [[Wiki Migration|ported]] to [[Moin Moin|MoinMoin]]),
+
When adding a new page to the table, make sure to add it to the [[:Category:WikiDocs Page|WikiDocs page]] category.
* a [[Moderated Wiki Mirror|ModeratedWikiMirror]] (probably realized through a [[Shadow Wiki|ShadowWiki]]),
 
* a [[Wiki Doc Converter|WikiDocConverter]] by which [[Wiki Doc Moderator|WikiDocModerator]]s can copy a specific version of a wiki page to the [[Moderated Wiki Mirror|ModeratedWikiMirror]],  
 
* a [[Wiki Web Service|WikiWebService]] that serves the content of the [[Moderated Wiki Mirror|ModeratedWikiMirror]] or the real [[MusicBrainz Wiki|MusicBrainzWiki]] where appropriate
 
* a new and reduced [[Main Site Structure|MainSiteStructure]] that serves as a portal to the [[Moderated Wiki Mirror|ModeratedWikiMirror]].  
 
  
[[Image:WikiDocsConcept.png]]
+
[[Category:Wiki]] [[Category:WikiDocs Page]]
 
 
==Related Implementations==
 
 
 
Related projects and ideas on other wikis:
 
* The general idea we are trying to realize is described as [http://wikifeatures.wiki.taoriver.net/moin.cgi/StagedCommits StagedCommits] on the [http://wikifeatures.wiki.taoriver.net/ WikiFeaturesWiki].
 
* [[Rhizome Wiki|RhizomeWiki]] is written in python and has a label attribute that can be set to "draft" or "released". The Wiki engine will display the latest released version. Search for "Label" on [http://rhizome.liminalzone.org/RhizomeManual#id1099155628 this page].
 
* There is some discussion on [http://www.usemod.com/cgi-bin/mb.pl?MeatballWiki MeatBall] on this: [http://www.usemod.com/cgi-bin/mb.pl?LayeredWikiInterface LayeredWikiInterface] and [http://www.usemod.com/cgi-bin/mb.pl?StableCopy StableCopy].
 
* There is a [http://www.srcf.ucam.org/~cjp39/Peri/StableCopy StableCopy] (also called [http://www.srcf.ucam.org/~cjp39/Peri/StableView StableView]) mechanism implemented on [http://www.srcf.ucam.org/~cjp39/Peri/PeriPeri PeriPeri]. This is not identical to the WikiDocs concept but it might be an alternative. Periperi is written in perl; see the [http://www.srcf.ucam.org/~cjp39/Peri/Source/peri.cgi source]. Captain solo tried to install Periperi and encountered some [http://captsolo.net/info/blog_a.php/2004/05/04/p497 problems]. Perhaps his experience helps. 
 
** [http://wikifeatures.wiki.taoriver.net/ WikiFeaturesWiki] calls this [http://wikifeatures.wiki.taoriver.net/moin.cgi/DelayedCommits DelayedCommits].
 
 
 
* [http://wwnew.linux-ha.org/WikiTransclusion WikiTransclusion] used by the High Availability Linux project for their documentation.
 
 
 
==Progress of this Project==
 
 
 
''The [[Wiki Docs Plan|WikiDocsPlan]] will describe the steps towards a complete WikiDocs system (I just don't have the time to write it up yet --[[User:DonRedman|DonRedman]])''
 
 
 
There has been a first attempt to do this in a separate wiki, but this has been stopped because of some concerns for this wiki.
 
 
 
[[User:DonRedman|DonRedman]] has written [[Don's WikiDocs Concept|DonsWikiDocsConcept]] to describe his concerns and offer a solution. This is of historical interest only. There is also a [http://lists.musicbrainz.org/pipermail/musicbrainz-advisors/2005-April/000049.html full discussion] (mostly between [[User:Dupuy|Dupuy]] and [[User:DonRedman|DonRedman]]).
 
 
 
Then [[User:RobertKaye|RobertKaye]] and [[User:DonRedman|DonRedman]] have met in Hamburg, drank some beer and thought of this [[WikiDocs Concept|WikiDocsConcept]]. 
 
 
 
[[User:JohnCarter|JohnCarter]] has taken up the job of the actual [[Wiki Migration|WikiMigration]], in which this wiki has been moved from [[Use Mod|UseMod]] ([http://oldwiki.musicbrainz.org former]) to [[Moin Moin|MoinMoin]] (current).
 
----
 
 
 
Can all WikiDocs moderators be listed, maybe on this page? --[[User:Zout|Zout]]
 
[[Category:To Be Reviewed]] [[Category:Documentation]] [[Category:Wiki]]
 

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.