Ubuntu Wiki

• Launchpad entry: [https://launchpad.net/distros/ubuntu/+spec/better-wiki-docs]

• Created: Date(2005-10-06T21:07:03Z) by JaneWeideman

• Contributors: MatthewEast, HenrikOmma, CoreyBurger, MatthewPaulThomas

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

[:FrontPage: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 [:UserDocumentation:the help on the Ubuntu wiki] (wiki.ubuntu.com), and [http://help.ubuntu.com/ 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 [:SystemInfo:5631 pages], only [:CategoryDocumentation:600] or so of which are help, even searching just the wiki produces many irrelevant results. For example, searching for "Bluetooth" returns [https://wiki.ubuntu.com/?action=fullsearch&context=180&value=Bluetooth&fullsearch=Text 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. 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.

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. The server currently at that address 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 a Moin wiki on the Canonical/Ubuntu server farm.

Configure this server to include the following features:

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

• Launchpad authentication

• customised theme, and possibly additional Macros/parsers (wiki:MoinMaster/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 wiki:MoinMaster/HelpOnProcessingInstructions and wiki:MoinMaster/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

2. For each page: grep for the string 'CategoryDocumentation'

3. IF Doc then copy the whole page directory to the new location

4. IF Flag liveRun = 1 THEN edit the page to redirect to info page

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

Get page names:

•    1 if __name__ == '__main__':
     2 
     3   from MoinMoin import PageEditor, wikiutil
     4   from MoinMoin.request import RequestCLI
     5   import re
     6 
     7   request = RequestCLI(url=url)
     8   # Get all existing pages in the wiki
     9   pagelist = request.rootpage.getPageList(user='')
  

Get page content and find 'CategoryDocumentation':

•    1   for pagename in pagelist:
     2     request = RequestCLI(url=url, pagename=pagename.encode('utf-8'))
     3     p = PageEditor.PageEditor(request, pagename, do_editor_backup=0)
     4     origtext = p.get_raw_body()
     5     if re.search("CategoryDocumentation",origtext):
  

Copy the complete page:

•    1       CALL SOME SHELL COMMANDS HERE
  

Update page to redirect:

•    1       if liveRun and changedtext and changedtext != origtext:
     2         print "Writing %s ..." % repr(pagename)
     3         p._write_file(changedtext)
  

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

• -- HenrikOmma

Hosting of html documentation on the new wiki

Integration of the distro documentation (currently hosted as html on [http://help.ubuntu.com/ help.ubuntu.com] with the Moin wiki. The distro docs are written in docbook xml and built as html. The best way of inserting them directly into the Moin wiki is via the html parser, testing is underway on the [http://help.ubuntu.com/wiki/FaqGuide help.ubuntu.com test wiki].

Ladder of trust

The end solution must make clear the level of expert participation in each type of documentation. A possible structure (for Edgy Eft) is:

• Official docs: http://help.ubuntu.com/edgy_eft/ (user comments allowed on each page but moderated by doc writers, informative ones get added to community docs. Adding comments is the lowest technical barrier to new users.)

• Community docs: http://help.ubuntu.com/edgy_eft/community/ (wiki based docs - can be linked from comments in the official docs. Structure would permanently mirror official docs, but allow for the creation of new sections. The pages would initially mirror the official docs - then see where it goes. Community docs would then provide ideas for the next set of docs while remaining version specific. Active until end of support cycle.)

• Ubuntu+1 docs: http://help.ubuntu.com/ubuntu+1/ (current snapshot of official docs for next release. Including the ability for user comments (doc-team moderated) to remain between syncs with the offically developed docs. On official release date this directory could simply be renamed.)

CategorySpec