WikiDocs Concept

From MusicBrainz Wiki
Revision as of 12:38, 19 March 2009 by Zout (talk | contribs) (removed author(s))

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 RobertKaye and 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 MainSite, a ModeratedWikiMirror and the real MusicBrainzWiki:

  1. 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.
  2. 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 WikiDocsModerators. 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).
  3. The wiki (This will be 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 WikiNames 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.

  • Additon: I expect this hierarchy to melt into the wiki. Probably the wiki will become more structured.

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

WikiZens 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.

WikiDocsModerators will be active WikiZens. They will use 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 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:

We also need a WikiDocsSchedule or WikiDocsPlan to describe when what will be done. Currently the first thing to do is that the wiki will be transferred to MoinMoin. MoinMoin has a couple of features that are indispensable for the whole thing to work. ZeroGravitas is working on a tool for WikiMigration.

There are a few more things that I did not have the time to describe yet:

  • 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 HomePageFragments.
  • A detailed WikiDocsPlan for the 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 WikiDocTranslators to edit the localization text in a "live" manner that does not require Subversion access. This is one of the reasons why we really need MoinMoin 1.3 but that'll have to wait.