BetterWikiDocs

Revision 23 as of 2005-10-26 08:26:39

Clear message

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

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.

  • 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

  • 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

n/a

Design

  1. Move Wiki Documentation - options:
    • Use help.u.c used for both stable and wiki based documentation, and wiki.u.c (or dev.u.c) used for development and community pages.
    • More radical - Split out wikis based on content (not distro) and use interwiki winks. These could run on separate machines and have separate search, but login should be managed centrally. Wiki instances might include: teams.u.c, help.u.c, teams.u.c, specs.u.c, and wiki.u.c.
      • I don't like this idea as I think that there is no point hiving off wiki pages unless there is a good reason: AFAICS there is only a good reason in the case of documentation.
    • Look into moin development like clustering and caching techniques (non exist so far AFAIK).

  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.

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

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
  2. The server at help.ubuntu.com would have to be good enough

  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.

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