BetterWikiDocs

Revision 47 as of 2006-02-22 10:57:01

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.

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

  • Documentation is not in one place - Currently there are [http://www.ubuntu.com/support/documentation two major documentation resources]. The first is the [http://help.ubuntu.com documentation released with the distribution], developed by the Documentation Team. The second is [:UserDocumentation:community contributed documentation] on the Ubuntu wiki. The fact that these two high-quality and comprehensive resources are in different places leads to two major problems:

    1. Fragmentation - the profile of documentation in general is diluted, as well as causing the user some confusion about where to look for documentation.

    2. Unreasonable distinction between Official and Non-Official docs - Currently there is a distinction between "Official" docs (help.ubuntu.com) and "Unofficial" docs (wiki.ubuntu.com). Such a distinction is illusory and misleading: the reality is that there are some extremely reliable documents, and documents with a lesser degree of reliablility. There is no line between the two, it's a question of degree, but even if there were, the correct line wouldn't be between Wiki docs and Help docs - there are some extremely valuable and reliable documents on the wiki.

    3. Lack of searchability - it is not possible for a user to do a single search through both sets of documentation.

  • Muddled searches - The Ubuntu wiki contains pages concerning development (300 developer specification pages), personal pages, general brainstorming, and just about everything and anything related to Ubuntu. There are [:SystemInfo:5631 pages] on the wiki, approximately [:CategoryDocumentation:600 pages] of which are Documentation. This causes extreme problems for users searching for solutions to their problems because a single search will turn up immense numbers of irrelevant information. For example, a single search for "Bluetooth", turns up [:https://wiki.ubuntu.com/?action=fullsearch&context=180&value=Bluetooth&fullsearch=Text:374 results].

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

Design

This spec aims at:

  • Locating both the community documentation on a single website (at help.ubuntu.com) and thus improving the profile of documentation within the Ubuntu community, with the following benefits:
    1. Documentation can be better advertised as existing on one website
    2. Users can find the documentation more easily
    3. More community members are attracted to contribute
  • Ensuring that the single documentation resource contains ONLY documentation and is therefore thoroughly usable and searchable for the user.

For the sake of clarity, the plan involves moving all documentation to one place, leaving the Ubuntu wiki as a developer and community discussion resource.

Implementation

There are three steps. A desirable preliminary step would be to implement the WikiLicensing spec.

Setup New Wiki

Setup a Moin wiki for use as help.ubuntu.com. The server used for the help website (http://help.ubuntu.com) is not powerful enough to handle particularly well all the requests which it receives, and this will become much more problematic 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 - 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 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.

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

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

CategorySpec