Summary

Ubuntu's online help and support documentation suffers from being on the same Ubuntu wiki used for several other purposes. This can be fixed by moving it to a separate wiki, with policies tailored to the writing of useful and reliable help.

Rationale

The main Ubuntu wiki incorporated the UbuntuDownUnder wiki in August 2005, and the Edubuntu wiki in October 2005 (see wiki/MergerPlan), so as to avoid fragmentation and duplication. But for help and support pages, being on this wiki causes several problems.

Design

All help documents currently on wiki.ubuntu.com should be moved to a single site, help.ubuntu.com/community. This will make the help easier to advertise, easier to find, easier to search and browse, and easier to contribute to.

A trusted wiki team should have the ability to rename and delete pages, and to edit certain core pages (such as the front page, and the main page for an Ubuntu release.) People not in the wiki team can still edit other pages, and create new pages of their own.

Redirects should be set up for existing URLs on wiki.ubuntu.com to the new URLs on help.ubuntu.com/community.

Implementation

There are three steps. A desirable preliminary step would be to implement the WikiLicensing spec.

Set up the new wiki

Set up a Moin wiki for use as help.ubuntu.com/community. The server currently at help.ubuntu.com is not powerful enough to handle particularly well all the requests which it receives, and this will become much worse once the wiki documentation is hosted at that address too. For this reason, we almost certainly need some Canonical server love.

Configure this server to include the following features:

This is all really easy.

Migration of pages

This involves two stages:

  1. Moving the pages
    • We'd probably need a script which does something like this (this would probably require some developer time):
      • Searches for pages which contain the phrase "CategoryDocumentation. Specifically, the script should search data/pages/PageName/revisions/latestrevision for that string, for all values of "PageName".

      • For each page as identified above, copies the relevant folder to the new wiki.
  2. Replace old pages with redirect solution. It is imperative to keep the old urls for important pages valid. There are two reasonable options. The script would also need to implement this for all the pages which have been moved.
    • Use #refresh to automatically redirect the user onto a new wiki page (not currently enabled on the Ubuntu wiki), see HelpOnProcessingInstructions and HelpOnConfiguration

    • Use #redirect onto a specifically created page with information about the change. The recent Italian wiki migration has done this, for example see the page ItalianSudo.

Script Algorithm

  1. Get list of all pages in the wiki with the string "CategoryDocumentation"

  2. IF Doc then copy the whole page directory to the new location
  3. IF Flag liveRun = 1 THEN edit the page to redirect to info page

Working prototype: migrate_pages.py

The script can be based on existing moin maintenance scripts, such as the globaledit.py script

Find documentation pages:

(remove from between the words Category and Documentation) (remove the from

Copy the complete page:

Update page to redirect:

(does this increment the page version or just over-write it?)

(It adds a new revision of the page)

Searchability

In the future, we would want to look at making a unified search which is capable of searching both the html official docs and the wiki based community docs. This can be done after the implementation of this specification, because otherwise the spec risks biting off more than it can chew.

Comments

See /talk for commenting on this spec.


CategorySpec

BetterWikiDocs (last edited 2008-08-06 16:38:32 by localhost)