Difference between revisions of "WikiDocs"

From MusicBrainz Wiki
(update to main server (Imported from MoinMoin))
(update (Imported from MoinMoin))
Line 1: Line 1:
 
=Basing the Documentation on the Wiki=
 
=Basing the Documentation on the Wiki=
  
[[Image:Alert.png]] '''''Warning''' the pages on WikiDocs are currently in transition.''  
+
[[Image:Alert.png]] ''The pages on WikiDocs are slowly getting up to date again.''  
  
 
This is [[Current Work|CurrentWork]].  
 
This is [[Current Work|CurrentWork]].  
Line 15: Line 15:
 
The structure of the WikiDocs system will be as follows:  
 
The structure of the WikiDocs system will be as follows:  
 
* All content resides in the [[MusicBrainz Wiki|MusicBrainzWiki]] (The [[Wiki Migration|WikiMigration]] to [[Moin Moin|MoinMoin]] was an essential precondition for this).  
 
* All content resides in the [[MusicBrainz Wiki|MusicBrainzWiki]] (The [[Wiki Migration|WikiMigration]] to [[Moin Moin|MoinMoin]] was an essential precondition for this).  
* [http://musicbrainz.org/edit/wikitransclusion/transclusion.html Wiki Transclusion Table]: [[WikiDocs Moderator|WikiDocsModerator]]<code><nowiki></nowiki></code>s select important wiki pages that should become [[WikiDocs Page|WikiDocsPage]]<code><nowiki></nowiki></code>s. They enter the last stable revision of that page into the [[Moderated Revision Table|ModeratedRevisionTable]] (see [[WikiDocs Moderator|WikiDocsModerator]] for usage description).  
+
* [http://musicbrainz.org/edit/wikitransclusion/transclusion.html Wiki Transclusion Table]: [[WikiDocs Moderator|WikiDocsModerator]]<code><nowiki></nowiki></code>s select important wiki pages that should become [[WikiDocs Page|WikiDocsPage]]<code><nowiki></nowiki></code>s. They enter the last stable revision of that page into the [[Wiki Transclusion Table|WikiTransclusionTable]] (see [[WikiDocs Moderator|WikiDocsModerator]] for usage description).  
 
* Users visiting the [[MusicBrainz Wiki|MusicBrainzWiki]] will see no difference.  
 
* Users visiting the [[MusicBrainz Wiki|MusicBrainzWiki]] will see no difference.  
* Users visiting the [[MusicBrainz Web Site|MusicBrainzWebSite]] will be served content from the wiki via a [[Wiki Web Service|WikiWebService]], which will  
+
* Users visiting the [[MusicBrainz Web Site|MusicBrainzWebSite]] will be served content from the wiki via a [[Wiki Web Service|WikiWebService]], which will check in the [[Wiki Transclusion Table|WikiTransclusionTable]] whether there is a moderated revision of the requested page.  
** Check in the [[Moderated Revision Table|ModeratedRevisionTable]] 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, 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 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.  
 
** If it is not, 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.  
Line 28: Line 27:
 
In the [[WikiDocs Concept|WikiDocsConcept]] the [[MusicBrainz Wiki|MusicBrainzWiki]] is seen as a ''community''. This community uses, changes and develops the content of docs, help pages, discussions, guidelines etc. 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.  
 
In the [[WikiDocs Concept|WikiDocsConcept]] the [[MusicBrainz Wiki|MusicBrainzWiki]] is seen as a ''community''. This community uses, changes and develops the content of docs, help pages, discussions, guidelines etc. 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, most of the wiki will be open for everyone to edit. We will not control the content in the wiki. We will, however, excerce some control over that part of the wiki's content which is integrated into the [[Main Site|MainSite]]. This happens via the [[Moderated Revision Table|ModeratedRevisionTable]].  
+
Thus, most of the wiki will be open for everyone to edit. We will not control the content in the wiki. We will, however, excerce some control over that part of the wiki's content which is integrated into the [[Main Site|MainSite]]. This happens via the [[Wiki Transclusion Table|WikiTransclusionTable]].  
  
 
===Accessing the Wiki===
 
===Accessing the Wiki===
Line 42: Line 41:
 
====Accessing the Wiki via the Wiki Web Service====
 
====Accessing the Wiki via the Wiki Web Service====
  
A visitor of [[MusicBrainz]] will first see the [[Main Site Stucture|MainSiteStucture]]'s content. Then he will seamlessly move into the WikiDocs which will be served to him via the [[Wiki Web Service|WikiWebService]]. If a page is not listed in the [[Moderated Revision Table|ModeratedRevisionTable]], the web service will serve the resepective page from the [[MusicBrainz Wiki|MusicBrainzWiki]]. None of these pages are editable.  
+
A visitor of [[MusicBrainz]] will first see the [[Main Site Stucture|MainSiteStucture]]'s content. Then he will seamlessly move onto [[WikiDocs Page|WikiDocsPage]]<code><nowiki></nowiki></code>s which will be served to him via the [[Wiki Web Service|WikiWebService]]. If a page is not listed in the [[Wiki Transclusion Table|WikiTransclusionTable]], the web service will serve the resepective 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.  
 
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.  
Line 63: Line 62:
 
* [http://wwnew.linux-ha.org/WikiTransclusion WikiTransclusion] used by the High Availability Linux project for their documentation.  
 
* [http://wwnew.linux-ha.org/WikiTransclusion WikiTransclusion] used by the High Availability Linux project for their documentation.  
  
==Progress of this Project==
+
==History 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]])''
+
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.  
 
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]]<code><nowiki></nowiki></code>s.
 +
</ul>
  
[[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]]).  
+
[[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]].   
 
Then [[User:RobertKaye|RobertKaye]] and [[User:DonRedman|DonRedman]] have met in Hamburg, drank some beer and thought of this [[WikiDocs Concept|WikiDocsConcept]].   
Line 84: Line 85:
 
* a new and reduced [[Main Site Structure|MainSiteStructure]] that serves as a portal to the [[Moderated Wiki Mirror|ModeratedWikiMirror]].  
 
* a new and reduced [[Main Site Structure|MainSiteStructure]] that serves as a portal to the [[Moderated Wiki Mirror|ModeratedWikiMirror]].  
  
----
 
 
Can all WikiDocs moderators be listed, maybe on this page? --[[User:Zout|Zout]]
 
 
[[Category:To Be Reviewed]] [[Category:Documentation]] [[Category:Wiki]]
 
[[Category:To Be Reviewed]] [[Category:Documentation]] [[Category:Wiki]]

Revision as of 13:44, 7 March 2006

Basing the Documentation on the Wiki

Alert.png The pages on WikiDocs are slowly getting up to date again.

This is CurrentWork.

WikiDocs Concept

The goal of WikiDocs is to base more of the main site's content on the very good documentation that has evolved in this wiki.

The main concept of WikiDocs is therefore that there will be no separate documentation. All docs will be in the 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 WikiDocsConcept for more details.

The Components of the WikiDocs

The structure of the WikiDocs system will be as follows:

The Wiki and WikiDocs

In the future the MusicBrainzWiki will be the source for all content of MusicBrainz. There will only be very few exceptions (about 20 pages that form the MainSiteStructure).

In the WikiDocsConcept the MusicBrainzWiki is seen as a community. This community uses, changes and develops the content of docs, help pages, discussions, guidelines etc. 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, most of the wiki will be open for everyone to edit. We will not control the content in the wiki. We will, however, excerce some control over that part of the wiki's content which is integrated into the MainSite. This happens via the WikiTransclusionTable.

Accessing the Wiki

The MusicBrainzWiki will be accessible in two ways:

  1. as a wiki, via wiki.musicbrainz.org/SomePage and
  2. through a WikiWebService via www.musicbrainz.org/doc/SomePage

Accessing the Wiki as a Wiki (via MoinMoin)

If you access the wiki through the MoinMoin interface, you will be able to edit (nearly) all pages. This interface (I think they are called "themes" in MoinMoin) has a look and feel that is similar to but still distinct from the MainSite. The main distinguishing factor is the black dotted border around the page's content.

Accessing the Wiki via the Wiki Web Service

A visitor of MusicBrainz will first see the MainSiteStucture's content. Then he will seamlessly move onto WikiDocsPages which will be served to him via the WikiWebService. If a page is not listed in the WikiTransclusionTable, the web service will serve the resepective page from the 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 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 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 WikiNeedsaNewCenter. We have therefore moved the center from HomePage to WikiHome. WikiHome should become the homepage for the wiki as a wiki. While the "homepage" for the moderated wiki content will of course be the 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 AntiSpamFeature (http auth) is a second barrier that I would really like to remove. I have searched for some alternative AntiSpamFeatures and listed them on that page.

Related Implementations

Related projects and ideas on other wikis:

  • WikiTransclusion used by the High Availability Linux project for their documentation.

History of this Project

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.

DonRedman has then written DonsWikiDocsConcept to describe his concerns and offer a solution. This is of historical interest only. There is also a full discussion (mostly between Dupuy and DonRedman).

Then RobertKaye and DonRedman have met in Hamburg, drank some beer and thought of this WikiDocsConcept.

JohnCarter has taken up the job of the actual WikiMigration, in which this wiki has been moved from UseMod (former) to MoinMoin (current).

Initial idea

This is the original WikiDocs concept which is now superceded by the one described above