BetterWikiDocs

Revision 38 as of 2006-01-25 09:29:38

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

This involves moving the wiki documentation to help.ubuntu.com and merging the distro documentation in with it.

Implementation

  1. Setup a Moin wiki (preferably version 1.5) on a good server for use as help.ubuntu.com. Configure this server to include the following features:

    • Access controls - normal users will not be able to delete/move pages. A wiki editor group will have control over certain core pages, such as the index and distro documentation. See HelpOnAccessControlLists

    • Launchpad authentication
    • Customised theme and possibly additional Macros
  2. Move Wiki Documentation (see below)

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.

Outstanding issues

This spec would require resolving the following issues:

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

  2. 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.
  3. Integration of the distro documentation with the Moin wiki. The distro docs are written in docbook xml. The alternative possibilities for hosting them on a moin wiki include:
    • Building html and inserting it wholescale into a single page with the HTML macro.
    • Using Moin's xml rendering capabilities - this would be unlikely to work, because Moin is unlikely to understand the entities and book structure.
    • By converting the xml into Moin format. We need to investigate the various tools that exist for this. Jeff Schering wrote an article2moin script, we need to see if this can work for books.

CategorySpec