User:Stewartadcock/article

An introduction to the wonderful world of WikiWikiWebs and one research group's experiences.

Abstract
A "WikiWikiWeb" enables documents to be authored collectively using nothing more than a web browser. The term "wiki" is commonly used as an abbreviation of WikiWikiWeb. A single document (i.e. a single web page) in a wiki is known as a "wiki page", and the entire set of pages, which are typically heavily interlinked, are called "the wiki". Software which implements a wiki is known as a "wiki engine".

Perhaps the most unusual thing about wikis is that you not only can edit all the web pages on the server from within the web page itself, but you should, whenever you think something needs updating! Usually, wikis may be freely modified by all persons who also have access to the wiki server. There is no review prior to acceptance of modifications. This leads to a powerful, community-based, collaborative editing environment.

The speed of creating and updating pages is one of the defining characteristics of wiki technology, as alluded to by the name; "Wiki wiki" means "very quick" in the Hawaiian language.

The McCammon group had a grossly out-of-date and awkward to maintain intranet website which was supposed to act as a repository of information required for day to day functioning of the group's research efforts. An experimental wiki, initially just containing information extracted from the McCammon group website, was implemented. Significant (in terms of both content and practical utility) new material was soon developed. Information may be readily updated, or corrected, without any understanding of archaic hypertext markup languages or any understanding of the group's web server configuration. This article introduces this wiki, codenamed "the McWiki".



Introduction to Wikis
The original wiki, the WikiWikiWeb can be found at http://c2.com/cgi/wiki. Although much useful content has been incorporated into that wiki, it mostly acts as an experimental sandbox for wiki users and developers. The world's largest wiki is the hugely successful Wikipedia, a free online encyclopedia with the English language edition at http://en.wikipedia.org/. A full description of Wikipedia may be found at http://en.wikipedia.org/wiki/Wikipedia.

Due to the relative simplicity of the basic wiki concept, a large number of implementations exist. These range from very simple (e.g. ZWiki, built on the Zope content management system) implementations that only provide the most fundamental functionality, through to those that are highly sophisticated content management environments (e.g. TWiki and the powerful MediaWiki.

One aspect of wikis that new users often have trouble grasping is the concept that nobody owns a particular page, or the content on that page. If somebody creates a new page in the wiki, that does not mean that they somehow own the information on that page or that they may veto other user's additions or changes. This might, on occasion, lead to personal disputes. Should you observe a change that you disagree with, instead of reverting or deleting it, you should make a comment at the base of the page. If the consensus is exhibited in the comments that an earlier change was wrong or poorly considered *then* remove it, improve it or correct it.

The "McWiki"
Given its simplicity and ease of setup, and its scope for customisation, ZWiki was selected for serving the prototype McWiki. Like much of the software used in the McCammon Group, ZWiki is open-source software available freely under the terms of the GNU General Public License. Zwiki is built on the Zope web application server. Zope is a Python-based dynamic website creation, website server and website authentication environment. This is running on top of a standard Apache web server installation. The beauty of the wiki is that nobody will ever need to know that, nor will they ever need to know how to program using Python. In fact, they would not even need to know how to use HTML (although, admittedly, that does help on certain occasions).

The majority of information on the McCammon Group intranet web pages was ported, to varying degrees of completeness, into the ZWiki environment. Much of this was done via a series of simple cut'n'paste operations. Where mistakes are known to exist in the website, these could be rapidly corrected. For example, Stewart's home and cell phone numbers are transposed on the website. It only required a mouse click, re-typing of the two numbers and another mouse click for this mistake to be fixed in the wiki.

Access permissions for the McWiki are the same as for the existing restricted access web pages. The main difference is that one does not need to have administrative powers, a knowledge of HTML, or of the particular Apache configuration in use to edit the pages.



Editing with ZWiki
Although knowledge of the HTML or XHTML markup that is usually used for implementing web pages is useful for certain (advanced) formatting such as tables, it is completely unnecessary for most users of wikis. The methods and rules for formatting vary slightly between the different wiki engines, but they are always simple. In this section, the most basic formatting rules for ZWiki are described.


 * **blank pages**: Occasionally, you might come across hyperlinked question marks. This indicates a link to another page in the wiki that does not actually exist.  You are strongly encouraged to create target pages for any such hyperlink.  This is done by following the hyperlink, which takes you directly to a page allowing you edit it.


 * **log-in**: Despite not being necessary, we would like to encourage people to log-in before editing. Near the bottom of each page, a link named UserOptions exists.  Prior to your first edit this should be clicked, and then you can enter your name of the page that appears.  This helps us to track who is responsible for changes, as listed on the RecentChanges page.


 * **comments**: At the base of every page, a editable text box exists for the purpose of quickly adding comments to that page. Again, you are encouraged to make use of this feature.


 * **editing**: To edit a page, click the "edit" link in the upper right corner of any page. This brings up a large text box containing that page's contents in its raw format.  Make any changes you desire, add a comment in the "Optional note" box and finally click on the "save" button.  That is all you need to do!


 * **markup**: Page formatting is performed automatically, but you may offer hints. The HelpPage has more detail, but the basic formatting rules are as follows:


 * Text surrounded with &#42;, &#42;&#42;, _ or ' are *italic*, **bold**, _underlined_ or 'mono-spaced', respectively.


 * Links are automatically created based on !WikiName's (i.e. page names in the current wiki), ![page names in square brackets], explicitly entered !URLs beginning with "http:" and so-called structured text-style links. In the editor, structured text-style links consist of the visible text surrounded by quotation marks followed by a colon and then the URL, like this: '"link to main website":http://mccammon.ucsd.edu/'.


 * One or more lines of text form a paragraph with blank lines separating paragraphs.


 * A single line "paragraph" followed by a more-indented paragraph becomes a heading.


 * A paragraph beginning with - or * or 0. and a space makes a bulleted or numbered list item. Any more-indented list items are rendered as sub-lists.


 * HTML tags may be incorporated if necessary. However, this is to be discouraged.


 * Some or all of the above rules may be overridden (known as "escaped") by putting a "!" symbol at the beginning of a link or a line. An alternative is to enclose text in single quotes.  An instance where escaping is useful is every time you enter the word "!McCammon", which is normally detected as a internal wikilink.  By typing "!!McCammon" the word does not get converted in to an erroneous wikilink.


 * **subscriptions**: Any user may "subscribe" to a page. Once subscribed, they will be notified by email when any modification occurs to that page.  The feature exists and is operational but, at present, you need to use your initiative to use it.

Potential problems
Formatting and markup rules and syntax tend to differ between the various wiki engines. While this does not pose a critical problem because it is usually much simpler than even HTML, the resulting learning curve might be an undesirable barrier to prospective editors.

Due to the freely editable nature (the fundamental characteristic, even) there is no immediate or formal editorial or peer-review process. Most wiki engines offer an auditable history, however, so the integrity of the data can usually be assured.

For a short period, the McWiki became the medium for discussions and debates (generally of a highly technical nature) within the group. Not surprisingly, it soon became apparent that Wikis are not suited to extended multi-party discussion. Resulting from this experience, the use of a wiki versus a mailing list (or bulletin board, or forum) was more appropriately chosen for the situation.

The benefits and future outlook
Wikis are ideal for collaborative editing of complex documents. The original basis for this article, for instance, was edited in place using the very wiki it discusses! This specific copy is hosted on the wikipedia servers under Stewart's Wikipedia personal user page.

Use of this new McWiki bestowed several important benefits to the group, including:


 * Easily maintained contact information. Anybody may add, correct, or update group contact details thus freeing the secretary to do more important (and probably more interesting) work.


 * Constantly maintained HOWTO and FAQ documents. No longer will there be any excuse for the grossly outdated information previously available on the group's restricted access website.  When a group member comes across something that is wrong or incomplete, they may readily fix it rather than fighting the gauntlet of HTML, non-standard Apache configurations, and UNIX permissions.  This is particularly useful for maintainence of documentation on non-standard modifications to research software.


 * A collaborative forum. Wikis provide a perfect environment for creating multi-authored documents.


 * Interactive documents. Every user has the ability to make comments on documents, enabling queries to be resolved and suggestions to acted upon "in place".


 * Auditable history. In theory, the wiki could be used as an electronic lab book, although nobody is doing this with the McWiki at present.

It is true that the information the McWiki contains is, in some places, poorly formatted or incomplete. Given that it is a Wiki, one hopes that each group member will fix one or two things as they are noticed. Since it is said that many hands make light work, the McWiki will rapidly become a valuable and complete information repository.

I do not claim that the ZWiki solution is perfect. A number of useful features, common to most wiki engines, are not implemented in ZWiki. Such features include edit previews, per-user themes, automatic tables of contents and automated resolution of edit conflicts (i.e. two edits on the same page at the same time). These flaws in ZWiki may be excused because it is exceptionally simple.