WikiDocs
Basing the Documentation on the Wiki
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 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 WikiPages as being 'stable' and transclude them into the website.
See WikiDocsConcept for the more sociological and WikiZen related details.
The Components of the WikiDocs
The structure of the WikiDocs system looks like this
- All content resides in the MusicBrainzWiki (The WikiMigration to MoinMoin was an essential precondition for this).
- There is a Transclusion Table that stores which revision of which page is considered 'stable'. WikiDocsModerator
s select important wiki pages that should become WikiDocsPage
s. They enter the last stable revision of that page into the WikiDocsTransclusionTable (see WikiDocsModerator for usage description). A page that is listed in the transclusion table is said to be "wikidocselt".
- Users visiting the MusicBrainzWiki will 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 MusicBrainzWebSite will be served content from the wiki via the WikiDocsTransclusionMechanism (aka WikiWebService), which will check in the WikiDocsTransclusionTable whether there is a moderated revision of the requested page.
- If it is, it will fetch that revision, do some 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.
The pages served by the webservice are not editable on the website.
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, exercise some control over that part of the wiki's content which is integrated into the MainSite. This happens via the WikiDocsTransclusionTable.
Accessing the Content
Content will be accessible in two ways:
- As a WikiPage via the MusicBrainzWiki at
wiki.musicbrainz.org/PageName
and - As a WikiDocsPage through the WikiDocsTransclusionMechanism (akla WikiWebService) at
www.musicbrainz.org/doc/SomePage
Accessing Content as a Wiki Page
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 Content as a WikiDocs Page
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 WikiDocsTransclusionTable, the web service will serve the respective 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:
- The general idea we are trying to realize is described as StagedCommits on the WikiFeaturesWiki.
- 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 this page.
- There is some discussion on MeatBall on this: LayeredWikiInterface and StableCopy.
- There is a StableCopy (also called StableView) mechanism implemented on PeriPeri. This is not identical to the WikiDocs concept but it might be an alternative. Periperi is written in perl; see the source. Captain solo tried to install Periperi and encountered some problems. Perhaps his experience helps.
- WikiFeaturesWiki calls this DelayedCommits.
- WikiTransclusion used by the High Availability Linux project for their documentation.
History of this Project
Our experience has shown, that maintaining WikiDocsPages is quite some work. Maybe we need a 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.
- Some of these pages still exist. They are viewable via
musicbrainz.org/wd/PageName
, and editable (to some) via http://wikidocs.musicbrainz.org/write/. All these pages will eventually be replaced by real WikiDocsPages.
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
- the MusicBrainzWiki (which will be ported to MoinMoin),
- a ModeratedWikiMirror (probably realized through a ShadowWiki),
- a WikiDocConverter (now WikiDocsConversion) by which WikiDocsModerators can copy a specific version of a wiki page to the ModeratedWikiMirror,
- a WikiWebService that serves the content of the ModeratedWikiMirror or the real MusicBrainzWiki where appropriate
- a new and reduced MainSiteStructure that serves as a portal to the ModeratedWikiMirror.