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! Apart from specs, there are many pages which clog up searches when users are searching for documentation.

• 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).

The above points mean that the wiki is currently not a good resource for documentation.

Design

1. Move Wiki Documentation - Use help.u.c for both stable and wiki based documentation, and wiki.u.c remains in use 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).

doc.u.c + help.u.c solution alternative

1. Set up help.u.c as a moin wiki with one page for each help document or document page.
   • No extra cruft so searches are clean
   • Use a simple end-user skin with no ability to edit. These pages are static and generated from the repository
   • Raw HTML generated with the docbook transform can be displayed with the HTML macro

   • See mock-up example here: http://help.ubuntu.com/wiki/SomeUbuntuDocPage

2. Set up the documentation team site on doc.ubuntu.com as a moin wiki and move all the doc team pages there, including 'how to join', 'how to write docs' and WIP documentation. Team plans a progress tracking pages would also go there.

3. Set up a page (like /docs) for officially released documentation that can have a whole tree of sub pages,

   • For each page on help.u.c there is a corresponding page at doc.u.c/docs containing information about that page or document

   • This page in turn has sub-pages containing different categories of information like /breezy and /dapper versions, /comments, further links, etc.

   • See an example here: http://65.111.164.72/SomeUbuntuDocPage

   • the actual page content is also located here in the /breezy and /dapper sub-pages. These are autogenerated as on help.u.c, but are still editable Yes, edits will get over-written by the next auto-export, but then you can easily see the change and make sure to push it into the docbook files.

   • Only docteam members can make new pages in /docs (through ACLs), but anyone can make new pages anywhere else on doc.u.c

4. If a general WIP page on doc.u.c matures to a level of high enough quality, it will be moved to the /docs section and a

   • A corresponding docbook entry must be made and the correct auto-export set up

Implementation

Infrastructure

• 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.
    • Specifically, the patch to enable authentication via launchpad is needed.

Migration

Two options here:

1. Migrating all documentation in one go.

   • 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)
2. Gradual migration:
   • We could move pages gradually, and replacing them with redirects (see outstanding issues no.3). This would avoid the difficulties with the script solution.
3. Two documentation wikis:
   • One possibly solution involves one wiki on doc.ubuntu and one on help.ubuntu. We would need an easy way to push docs to help. Once they are on help, we need an easy way to make sure they don't bitrot. Possibly we need two moin installations, with a publishing mechanism. One each there would be a talk page associated with the page. With the doc.u.c wiki, anybody could edit. With the help.u.c, editing would only be allowed with the doc team, with anybody being able to add a comment.

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. We need to evaluate whether the server at help.ubuntu.com is 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.

4. Evaluate possibility of using a 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.

CategorySpec