BetterWikiDocs
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 7 results], even though only 3 of those results are documentation. 4 are developer related. 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, as well as the fact that it is more difficult to advertise the various help resources.
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 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
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:
- 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.
- We'd probably need a script which does something like this (this would probably require some developer time):
- 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.
Use #refresh to automatically redirect the user onto a new wiki page (not currently enabled on the Ubuntu wiki), see wiki:MoinMaster/HelpOnProcessingInstructions and wiki:MoinMaster/HelpOnConfiguration
Use #redirect onto a specifically created page with information about the change. The recent Italian wiki migration has done this, for example see the page ItalianSudo.
Script Algorithm
- Get list of all pages in the wiki
For each page: grep for the string 'CategoryDocumentation'
- IF Doc then copy the whole page directory to the new location
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:
Get page content and find 'CategoryDocumentation':
Copy the complete page:
1 CALL SOME SHELL COMMANDS HERE
Update page to redirect:
(does this increment the page version or just over-write it?)
-- HenrikOmma
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/FaqGuide2 help.ubuntu.com test wiki].