WikiDocs Concept: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(migration fix, added to CategoryWiki (Imported from MoinMoin))
 
(Redirecting to WikiDocs)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
#REDIRECT [[WikiDocs]]
=Basing the Documentation on the Wiki=

This is a common concept of the new [[WikiDocs]], a feature that will base most of the docs of the main site on the wiki. This has been thought out by [[User:RobertKaye|RobertKaye]] and [[User:DonRedman|DonRedman]] on April 27th 2005 over a few beers.

==General Idea==

When a programmer and a pedagogue work together, the outcome is ''both'' sociological and technical. Please keep this in mind when reading this. For example I will talk about the wiki as the wiki community (sociological) or as the wiki program (technical). Both aspects are interconnected.

The principle of the [[WikiDocs]] is that the generation of content must remain within the wiki community. You can think of this community like an open source software development community: The wiki text is the source code. There are people who know stuff and write text, and there are people who ask questions and point at pages that are not helpful or inaccurate. Think of the latter as bug reports. If you keep the "bug reporters" out of the documentation, then the whole work of keeping the docs up to date rests on the shoulders of the "programmers". Not good.

The wiki offers a dynamics in which the docs are kept up to date "magically" just by using them. So the first rule is to '''leave the wiki alone'''.

The wiki has, however, some inconveniences. The most important are:
* It is unstructured. The wiki is a flat cluster of pages. It is really easy to get lost there.
* There is no means of controling the content. While this is also a cool thing about wikis, it is a serious problem for pages that give a newcomer the first impression of [[MusicBrainz]]. The damage that a spammer can do in this case is quite large.

Therefore we need a system that gives a '''structured introduction''' to the wiki and some kind of '''moderation'''. ''But'' both have to leave the wiki community alone so that it can continue to produce the superior content that is has produced in the last year.

The mechanisms that will provide these features are:
* A '''minimalist home page''' that will be a '''portal''' to the wiki, and
* A '''moderated mirror''' of the important pages of the wiki.

==Structure of the System==

There will be three components with three different roles: the [[Main Site|MainSite]], a [[Moderated Wiki Mirror|ModeratedWikiMirror]] and the real [[MusicBrainz Wiki|MusicBrainzWiki]]:
# '''[[Main Site|The main site]]''' using Mason. This will be reduced to (ideally) about 20 pages. All the other content will be moved to the wiki. Visitors of the homepage will, however, see a moderated mirror of the wiki and not the real wiki itself for the most important pages. This component has the role of '''providing structure'''.
# '''[[Moderated Wiki Mirror|A mirror of important wiki pages]]''' that is an intermediate state between the main site and the real wiki. Pages will be copied over from the real wiki into this mirror by [[Wiki Doc Moderator|WikiDocModerator]]s. The moderators will thus '''exert control''' over what visitors see, but ''not'' over what [[WikiZen]]"s write. The moderators thus do something like Apple does with Linux (see below for the technical implementation of this component).
# '''[[MusicBrainz Wiki|The wiki]]''' (This will be [[Moin Moin|MoinMoin]] 1.3). This will be the real wiki hosting a real wiki community. The community will be aware that their role is to '''produce content''', and that this content will be used on the main site. Also, the pages will have to have good [[Wiki Name|WikiName]]s and be well intertwingled, so that they become an integral part of the wiki community. If the pages would have funky names, the community could not take care of them.

==User Experience==

===From the point of view of a visitor===

For a visitor the main site and the [[WikiDocs]] pages will look the same. Since the main site is hierarchically structured and points to some pages in a structured way, visitors will have an illusion of a hierarchy that is one level deeper that it really is. E.g. if the hierarchy of the main site's pages is two levels deep, then the first degree of links will feel like a third level in the hierachy.
<ul><li style="list-style-type:none">''Additon: I expect this hierarchy to melt into the wiki. Probably the wiki will become more structured.''
</ul>

As long as a user navigates through main site pages or [[WikiDocs]] pages everything looks like the main site. As soon as he klicks on a link that is only in the real wiki, he will be directed to an uneditable mirror of the real wiki. But these pages will look very differently. They will have a design and some notes that make clear that the user is in the wild now.

===Fron the point of view of a WikiZen===

[[WikiZen]]s will just use the wiki as they used to do. They might even use the main site more often, as they too need some structure sometimes.

[[Wiki Doc Moderator|WikiDocModerator]]s will be active [[WikiZen]]s. They will use [[Moin Moin|MoinMoin]]'s superior subscription features to keep an eye on the pages that they moderate. This way they can review changes to important pages and copy them over to the [[Moderated Wiki Mirror|ModeratedWikiMirror]]. Now it is time to explain how this is supposed to work technically.

==Technical Implementation==

The implementation is explained on a page for each component:
* the [[MusicBrainz Wiki|MusicBrainzWiki]]
* the [[Moderated Wiki Mirror|ModeratedWikiMirror]] (or [[Shadow Wiki|ShadowWiki]])
* the [[Wiki Doc Converter|WikiDocConverter]] by which [[Wiki Doc Moderators|WikiDocModerators]] can copy a specific version of a wiki page to the [[Moderated Wiki Mirror|ModeratedWikiMirror]],
* the [[Wiki Web Service|WikiWebService]] that serves the content of the [[Moderated Wiki Mirror|ModeratedWikiMirror]] or the real [[MusicBrainz Wiki|MusicBrainzWiki]] where appropriate
* the new and reduced [[Main Site Structure|MainSiteStructure]] that serves as a portal to the [[Moderated Wiki Mirror|ModeratedWikiMirror]].

We also need a [[Wiki Docs Schedule|WikiDocsSchedule]] or [[Wiki Docs Plan|WikiDocsPlan]] to describe when what will be done. Currently the first thing to do is that the wiki will be transferred to [[Moin Moin|MoinMoin]]. [[Moin Moin|MoinMoin]] has a couple of features that are indispensable for the whole thing to work. [[User:ZeroGravitas|ZeroGravitas]] is working on a tool for [[Wiki Migration|WikiMigration]].

... <pre>There are a few more things that I did not have the time to describe yet:
</pre>
* [[Nodocs Tags|NodocsTags]]: XML <nodocs> tags that get ignored in the shadow wiki
* Some special wiki pages that are not part of the wiki community and that are accessed by mason to provide easily updatable content for the main site. Robert called those [[Home Page Fragments|HomePageFragments]].
* A detailed [[Wiki Docs Plan|WikiDocsPlan]] for the [[Wiki Migration|WikiMigration]] from the current state to a fully [[WikiDocs]] featured site.
* The plan is to use [[WikiDocs]] to provide internationalization for the main site pages (both static and dynamic!); this will allow [[Wiki Doc Translator|WikiDocTranslator]]s to edit the localization text in a "live" manner that does not require CVS access. This is one of the reasons why we really need [[Moin Moin|MoinMoin]] 1.3

but that'll have to wait.

----Author: [[User:DonRedman|DonRedman]]

[[Category:To Be Reviewed]] [[Category:Development]] [[Category:Wiki]]

Latest revision as of 02:27, 25 October 2009

Redirect to: