WikiDocs: Difference between revisions
From MusicBrainz Wiki
Jump to navigationJump to search
PavanChander (talk | contribs) mNo edit summary |
PavanChander (talk | contribs) (Condensed & simplified; only relevant content kept.) |
||
| Line 1: | Line 1: | ||
==WikiDocs Concept== |
== 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 main concept of WikiDocs is therefore 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 [[Subversion]]. 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. We mark certain revisions of the most important [[Wiki Page|WikiPage]]s as being 'stable' and transclude them into the website. |
|||
| ⚫ | |||
See [[WikiDocs Concept|WikiDocsConcept]] for the more sociological and [[WikiZen]] related details. |
|||
| ⚫ | 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. |
||
==The Components of the WikiDocs== |
|||
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|FAQ]s] 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. |
|||
| ⚫ | |||
| ⚫ | |||
* There is a [http://musicbrainz.org/edit/wikitransclusion/transclusion.html Transclusion Table] that stores which revision of which page is considered 'stable'. [[WikiDocs Moderator|WikiDocsModerator]]s select important wiki pages that should become [[WikiDocs Page|WikiDocsPage]]s. They enter the last stable revision of that page into the [[Wiki Docs Transclusion Table|WikiDocsTransclusionTable]] (see [[WikiDocs Moderator|WikiDocsModerator]] for usage description). A page that is listed in the transclusion table is said to be "wikidocselt". |
|||
| ⚫ | |||
* Users visiting the [[MusicBrainz Web Site|MusicBrainzWebSite]] will be served content from the wiki via the [[Wiki Docs Transclusion Mechanism|WikiDocsTransclusionMechanism]] (aka [[Wiki Web Service|WikiWebService]]), which will check in the [[Wiki Docs Transclusion Table|WikiDocsTransclusionTable]] whether there is a moderated revision of the requested page. |
|||
** If it is, it will fetch that revision, do some [[WikiDocs Conversion|WikiDocsConversion]], and serve that content on the website. |
|||
** If it is not, the webservice serves the current revision of the normal wiki page, but with a warning that this is unmoderated content. |
|||
| ⚫ | |||
Therefore the 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 == |
|||
In the future the [[MusicBrainz Wiki|MusicBrainzWiki]] will be the source for ''all'' content of [[MusicBrainz]]. There will only be very few exceptions (about 20 pages that form the [[Main Site Structure|MainSiteStructure]]). |
|||
| ⚫ | |||
| ⚫ | |||
| ⚫ | |||
Thus, most of the wiki will be open for everyone to edit. We will not control the content in the wiki. We will, however, exercise some control over that part of the wiki's content which is integrated into the [[Main Site|MainSite]]. This happens via the [[Wiki Docs Transclusion Table|WikiDocsTransclusionTable]]. |
|||
| ⚫ | |||
# [[Transclusion Editor|Transclusion editors]] add/maintain entries on the [http://musicbrainz.org/edit/wikitransclusion/transclusion.html transclusion table] for pages that require controlled transclusion. |
|||
| ⚫ | |||
# 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. |
|||
#* 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. |
|||
| ⚫ | |||
===Accessing the Content=== |
|||
| ⚫ | |||
Content will be accessible in two ways: |
|||
# As a [[Wiki Page|WikiPage]] via the [[MusicBrainz Wiki|MusicBrainzWiki]] at <code><nowiki>wiki.musicbrainz.org/PageName</nowiki></code> and |
|||
# As a [[WikiDocs Page|WikiDocsPage]] through the [[Wiki Docs Transclusion Mechanism|WikiDocsTransclusionMechanism]] (akla [[Wiki Web Service|WikiWebService]]) at <code><nowiki>www.musicbrainz.org/doc/SomePage</nowiki></code> |
|||
====Accessing Content as a Wiki Page==== |
|||
If you access the wiki through the [[Moin Moin|MoinMoin]] interface, you will be able to edit (nearly) all pages. This interface (I think they are called "themes" in [[Moin Moin|MoinMoin]]) has a look and feel that is ''similar to but still distinct from'' the [[Main Site|MainSite]]. The main distinguishing factor is the black dotted border around the page's content. |
|||
====Accessing Content as a WikiDocs Page==== |
|||
A visitor of [[MusicBrainz]] will first see the [[Main Site Stucture|MainSiteStucture]]'s content. Then he will seamlessly move onto [[WikiDocs Page|WikiDocsPage]]s which will be served to him via the [[Wiki Web Service|WikiWebService]]. If a page is not listed in the [[Wiki Docs Transclusion Table|WikiDocsTransclusionTable]], the web service will serve the respective page from the [[MusicBrainz Wiki|MusicBrainzWiki]]. None of these pages are editable. |
|||
The page a user sees is directly taken from the wiki. It has the same look and feel like the [[Main Site|MainSite]]. If the content has not been moderated, it will be shown within the same black dotted border that signals "this is work in progress". There should probably also be a note that says that this page is maintained by the wiki community and a link to the same page in the [[Moin Moin|MoinMoin]] wiki interface so that it can be edited there. |
|||
===Changes in Wiki Culture=== |
|||
The wiki community will have to be very aware that they create the content for the home page. Then [[Wiki Needsa New Center|WikiNeedsaNewCenter]]. We have therefore moved the center from [[Wiki Home|HomePage]] to [[Wiki Home|WikiHome]]. [[Wiki Home|WikiHome]] should become the homepage for the wiki as a wiki. While the "homepage" for the moderated wiki content will of course be the [[Main Site|MainSite]]. |
|||
Also, I suppose that the wiki itself should be opened up some more. The transclusion mechanism keeps people who do not want to deal with wiki nature effectively out of the wiki. Our current [[Anti Spam Feature|AntiSpamFeature]] (http auth) is a second barrier that I would really like to remove. I have searched for some alternative [[Anti Spam Feature|AntiSpamFeature]]s and listed them on that 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. |
|||
==History of this Project== |
|||
Our experience has shown, that maintaining [[WikiDocs Page|WikiDocsPage]]s is quite some work. Maybe we need a [[Helpful Transclusion Interface|HelpfulTransclusionInterface]]. |
|||
WikiDocs is now live on the main server. The remainder of this page provides some historical information about the progress of the project. |
|||
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. |
|||
<ul><li style="list-style-type:none">Some of these pages still exist. They are viewable via <code><nowiki>musicbrainz.org/wd/PageName</nowiki></code>, and editable (to some) via [http://wikidocs.musicbrainz.org/write/ http://wikidocs.musicbrainz.org/write/]. All these pages will eventually be replaced by real [[WikiDocs Page|WikiDocsPage]]s. |
|||
</ul> |
|||
[[User:DonRedman|DonRedman]] has then 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). |
|||
====Initial idea==== |
|||
''This is the original WikiDocs concept which is now superceded by the one described above'' |
|||
* the [[MusicBrainz Wiki|MusicBrainzWiki]] (which will be [[Wiki Migration|ported]] to [[Moin Moin|MoinMoin]]), |
|||
* a [[Moderated Wiki Mirror|ModeratedWikiMirror]] (probably realized through a [[Shadow Wiki|ShadowWiki]]), |
|||
* a [[Wiki Doc Converter|WikiDocConverter]] (now [[WikiDocs Conversion|WikiDocsConversion]]) by which [[WikiDocs Moderator|WikiDocsModerator]]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]]. |
|||
| ⚫ | |||
Revision as of 02:27, 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 by the consensus of the Musicbrainz user community (such as the [[Frequently Asked Questions|FAQ]s] 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 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:
- Leaving the wiki open for mass collaboration on http://wiki.musicbrainz.org/.
- Providing transclusion editors with the means to control what is viewable on http://musicbrainz.org/doc/.
WikiDocs Structure
The structure of the WikiDocs system looks like this:
- All content resides in the MusicBrainz Wiki.
- Transclusion editors add/maintain entries on the transclusion table for pages that require controlled transclusion.
- 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 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.
