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

• Packages affected: None (website)

Summary

The documentation on the wiki suffers from a number of problems which are broadly caused by the fact that the current wiki serves many purposes at the same time. This spec aims to move the documentation to a separate wiki.

Rationale

We merged the UDU wiki into the main Ubuntu wiki in August and the Edubuntu wiki followed in October (see ["wiki/MergerPlan"]. This followed a general policy of not fragmenting wiki's if at all possible. There are some benefits to having all content gathered in one place, but, in the case of documentation, some drawbacks have become apparent. For clarity, the example of a user trying to setup Bluetooth will be used in what follows.

The following problems arise with regard to the documentation currently on the wiki:

• The wiki has a vast quantity of non-documentation, which is muddling for users in searches. For example, if a user searches page titles for "Bluetooth", he finds [https://wiki.ubuntu.com/?action=fullsearch&context=180&value=Bluetooth&titlesearch=Titles 5 results], even though only 2 of those results are documentation. If he does a text-based search, the results are much worse.

• The wiki has many specs with addresses that look like documentation (e.g. BluetoothSupport) which means that users waste time going looking for red herrings. This problem is related to the first one. For a list of all the Specs, see CategorySpec. There are about 140 of them!

• The wiki documentation is not in the same place as the static documentation released by the Documentation Team at [http://help.ubuntu.com help.ubuntu.com] - this leads to users having to search more than one place and general fragmentation of documentation.

• There is a team of editors on the wiki (WikiTeam) but because all users have the same rights, pages occasionally get rewritten, moved and deleted in ways which create non-trivial problems.

• The performance/speed of the wiki has degraded as the number of pages and revisions have increased.
• People cannot find their documentation as easily as they should because (a) it is in more than one place (as explained above) and (b) there is no obvious link to it from the main Ubuntu website (the tab "Wiki" is not helpful, and the "Support" area is out of date).

Use cases

n/a

Scope

Ubuntu wiki, website

Design

1. Move Wiki Documentation - Use help.u.c for both stable and wiki based documentation, and wiki.u.c (or dev.u.c) for development and community pages.

2. Stop people deleting/renaming pages - A workable solution for the problem with people deleting and renaming pages is to implement access level control: thus is it possible to limit delete/rename rights to a group of editors who know what they are doing, and leave editing rights open to all. See HelpOnAccessControlLists. This _could_ be implemented on the current Ubuntu wiki, but it would lead to inconvenience for developers (e.g. MOTU) who work on fast changing pages, which often need to be deleted and renamed.

3. Improve the visibility of the documentation in general - options:
   • Make a "help" tab on the top of the Ubuntu website which points to help.ubuntu.com, where users can find both static documentation and wiki documentation. Space for this tab could be done by merging "Support" and "Partners" or by some similar means.
   • Include a prominent link with a similar effect to that under the "Support" tab of the website (less powerful solution).

Implementation

Code

• If the decision is taken to move the documentation to a wiki at help.ubuntu.com, we'd need the following:
  • A second installation of moin with the same tweaks as on the Ubuntu wiki would be required at help.ubuntu.com.

  • We'd need to do some work to get a more complete list of documentation at CategoryDocumentation.

  • We'd probably need a script which does something like this (this would probably require some developer time):

    • Does a FullSearch on CategoryDocumentation and identifies the pages in that category. The problem with this is that page (a) is not an exhaustive list of all documents on the wiki, and (b) has some pages on it that simple refer to it but are not documentation, such as this one. However, the category is a good starting point.

    • For each page as identified above, copies the relevant folder to the new wiki.
    • For each page as identified above, looks for the latest revision in data/pages/PageName/current and then edits the corresponding file in data/pages/PageName/revisions to replace the page content with what is chosen as the new content (see outstanding issues no.3)
  • Alternatively, a gradual migration procedure could be undergone, moving pages gradually, and replacing them with redirects (see outstanding issues no.3). This would avoid the difficulties with the script solution.

Data preservation and migration

The migration to a new server can be done by identifying the relevant pages (CategoryDocumentation is a start, but is not a complete list) and copying them to the new server. Moin permits this to be done with a simple cp command. A script might be required to copy all such pages over and apply whatever solution is adopted for the old pages.

Outstanding issues

This spec would require resolving the following issues:

1. Any new wiki would need to use Launchpad authentication, so we would need to apply spiv's user.py patch to the new installation. This _might_ be non-trivial, especially if there is a significant version difference between the two wikis. We should try and use the same Moin version if possible.
2. The server at help.ubuntu.com would have to be good enough, power wise. It is currently a serverpronto server with 512MB RAM and a SEMPRON 2400+.

3. Problems with moving the wiki documentation would mainly involve LINK-BREAKING. For example: a google search for Ubuntu Wiki Sudo leads to: RootSudo. Lots of people will have that page bookmarked. Moving the documentation would break this link. There are a number of possible solutions to such a problem, none of which are perfect:

   • 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. The recent Italian wiki migration has done this, for example see the page ItalianSudo.

   • Newer moin version. The newer versions support nicer userfacing features. We might also want to get involved in upstream development to influence them towards what we need.

BoF agenda and discussion

Please note that 1/3 of the participants to this BOF will be at Ubuntu Below Zero, and the spec may not therefore be an ideal candidate for a scheduled session. However we would appreciate some eyeballs on this and input!

CategorySpec