BetterWikiDocs

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.

  • Help is not in one place. Currently the help on the Ubuntu wiki (wiki.ubuntu.com), and the help shipped with Ubuntu (also available at help.ubuntu.com), are two separate sets of documents. So those people who instinctively look to the Internet to answer their problems and end up on wiki.ubuntu.com are unlikely to guess that there is also help available at help.ubuntu.com, and vice versa. (Even if they were aware, it is bad to make them hop from site to site when that can be avoided.) Conversely, contributors to the wiki may unwittingly duplicate work that has already been done for the "official" help documents, and vice versa.

  • And about that "official" thing... Much of the "unofficial" help written on the wiki is contributed by volunteers just as knowledgable as those writing the the official docs on help.ubuntu.com. The wiki has a lot of reliable help, along with some less reliable, so help.ubuntu.com is sacrificing a lot of comprehensiveness in return for not much extra trustworthiness.

  • Lack of visibility. As the Ubuntu wiki's FrontPage shows vividly, help documents are sharing the same wiki as documents about development, marketing, bureaucracy, artwork, individual contributors, and general brainstorming. This makes it unnecessarily difficult to find help, and lowers the profile of the documentation for users and contributors alike.

  • Lack of searchability. Because some help documents are shipped with Ubuntu and others are found only on the wiki, they cannot be searched all at once. And because the wiki contains 5631 pages, only 600 or so of which are help, even searching just the wiki produces many irrelevant results. For example, searching for "Bluetooth" returns 374 results.

  • Lack of structure. Partly because help documents are mixed in with documents of many other types, they are not consistent in their presentation and organization.

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:

  • access controls, with normal users not being able to delete/move pages (see HelpOnAccessControlLists)

  • Launchpad authentication

  • customised theme, and possibly additional Macros/parsers (HelpOnParsers) for adding html documentation.

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: 

  •    1 if __name__ == '__main__':
   2 
   3   from MoinMoin import PageEditor, wikiutil
   4   from MoinMoin.request import RequestCLI
   5   from MoinMoin import search
   6 
   7   query = search.QueryParser().parse_query('Category``Documentation')
   8   results = search.searchPages(request, query)
   9   for hit in results.hits:
  10       page = PageEditor.PageEditor(request, hit.page_name, do_editor_backup=0)

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

Copy the complete page: 

  •    1       shutil.copytree(page.getPagePath(), destination)

Update page to redirect: 

  •    1       if liveRun:
   2         print "Writing %s ..." % repr(pagename)
   3         page._write_file("#refresh 0 http://help.ubuntu.com/community/" + 
   4                          wikiutil.quoteWikinameURL(page.page_name))

(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)