Difference between revisions of "Wiki Usage Notes"

Latest revision as of 19:14, 21 December 2006

There are many good reasons to set up a wiki; to allow many people to write in the same space about the same subject, with document version history automatically tracked and the results of edits displaying instantly are a couple of compelling reasons. The other positive reason is that writing on a wiki does not require understanding of HTML, or potentially complex layout and formatting systems such as CSS.

Please Note: This document is written assuming a basic familiarity with WikiText on the part of the reader.

Creating a Wiki Page

For some the fun part of a wiki is merely reading what others write. For most though, it is as much fun or more to create and edit pages. This section of this page is intended to provide some helpful tips or just some conversation pieces on the topic.

Starting New Pages: Why Searching is Good

There are many ways to trick the Wiki engine into generating the "create this page" prompt, but in my experience, I find typing the name of the proposed new page into the Special:Search box is the best method.

The obvious advantage is that if someone has started a page along similar lines to the proposed new page, one can find out and contribute to the existing page before running too far down our own avenue, but if the search comes up blank, the option to create a new page will be present on the search results screen to be clicked on.

To Edit or to Word Process

One of the strengths of a wiki is that it is accessible and editable via the same medium, and that medium is generally the Internet. Put another way, if you can see it you can create or edit on it. While this is the cool part of a wiki, it is not always recommended. If one wishes to keep offline backups of content or to check spelling interactively, it is sometimes better to write in a word processor and copy/paste into the wiki.

Preview for the Greater Good

Sometimes editing and saving on a wiki is almost too easy. When a document is saved on a wiki, a version tracking entry for the page is automatically generated. This affords administrators and privileged users of the wiki the ability to roll back to older versions should something go awry, and allows everyone to see differential versions of pages and other cool things.

However, if one clicks save compulsively after every minor edit, this can become cumbersome for the Wiki engine, and while minor edits can be filtered out from the viewers point of view, that data is still stored somewhere.

So in my opinion, it is better to use the preview button to see incremental changes made as a document is being edited, and to only save at key points or milestones in the document's creation process, such as when a new major section has been written.

Formatting a Wiki Page

While it is true then that one can simply type into the edit box and hit Save, it is also true that a little understanding of WikiText - the language of the Wiki - can aid in producing complex looking documents, with a minimum of technical input.

Tables of Contents and Section Header Usage

One of the simplest things to do on a Wiki page is to create the "Table of Contents" seen at the top of most wiki pages. It's simple because the wiki software does it for you, if you give it a little hint.

The key to this hint is Section Headings, which are created by enclosing a short line of text between equals' signs. The real trick is that different levels of headings can be created by using different numbers of equals' signs and this in turn helps the wiki software to create a nicely formatted table of contents.

My personal style when creating pages on this wiki is to use two equals' signs to create headings for major sections in my article, and three equals' signs to denote a subsection of that major section.

In this way, as one moves linearly down the editing page, a structure of headings will appear; major headings wrapped in pairs of two equals' signs with groups of related headings below wrapped in pairs of three equals' signs, until a new major heading appears, again wrapped in pairs of two equals' signs, and the whole structure begins again. This kind of structuring helps the wiki create a logically formatted contents table, and tends to create easy to follow pages with easy to reference subsections.

Linking to Subsections of Pages

If a page on the wiki is laid out using the section header method described above, it becomes very easy to reference a particular section of the page; one only needs to create a Wiki Link constructed of the page name followed by a hash or pound sign ("#") and then the section name. A formal title for the link can then be applied by typing a vertical bar or pipe symbol ("|") and then the description to be displayed.

For example, to link to the page formatting section above, the WikiLink for this looks like this: [[Usage Notes#Formatting a Wiki Page|page formatting section above]].

Adding Media to a Wiki Page

As well as making it easy to edit pages in a purely textual form, the Wiki Engine also makes it quite easy to add images and other media to wiki pages.

Search for the Image on the Wiki

The first step in adding an image to a page is to see if one already exists that matches the required image. This can be easily accomplished by reviewing and searching the list of files uploaded to the wiki. If the image does not already exist, it can instead be uploaded via the upload form.

Uploading an Image

The first step in adding a new image to a page is to upload it to the wiki server via the upload form. The image should be in a format the wiki understands, such as PNG or possibly JPEG. It is usually best to crop and size the image to the required dimensions before uploading it.

The filename in the "Destination filename" box on the upload form becomes the name of the image once it has been stored on the Wiki server. This name should be something short and logical that is also reasonably descriptive. Any more detailed notes can be filled out in the summary field.

Displaying an Image

Once the image has been uploaded, it is easy to display on any page of the wiki; simply insert a WikiLink with the special type "Image" followed by a colon followed the wiki filename of the image.

For example, the following WikiLink would insert the "Gathering of Dragons" photo by Xiandria Gwynneville into a page: [[Image:GatheringOfDragons.png]].

To create a frame around the image and add a caption, the following WikiLink format can be used: [[Image:GatheringOfDragons.png|frame|Gathering of Dragons (Photo: Xiandria Gwynneville)]]. This would insert the "Gathering of Dragons" photo as seen on the Limbo Dragon Species page.

Categories: Make the Wiki Engine Do Our Work

One of the things computers are good at doing is keeping track of things that they're told to remember. Categories in the wiki are really just lists of pages maintained by the Wiki Engine. This is really cool because the writers using the wiki don't have to remember to update index and contents pages themselves; with categories one simply adds a page to a category and the main index page for that category updates itself automatically.

Adding a Page to a Category

To add a page to a category, insert a specially formatted WikiLink at the bottom of the document. Pages can belong to several categories; just add a category WikiLink for each one the page needs to belong to. The WikiLink format is the word "Category" followed by a colon followed by the category name.

For example, this page is part of the Wiki Help Category because it has the text [[Category:Wiki Help]] at the bottom.

Linking to a Category's Index Page

A small problem with categories for the beginning wiki user is that it's hard to link to them; if you put a traditional link to one on a page, that page becomes part of the category. While that is useful, sometimes one wants to display the category index page instead. How do we link to it then? The answer lies in the full colon (":") punctuation mark.

WikiLinks beginning with a colon will ignore their special Wiki Engine meanings and function like normal links. So to link to a category you make a normal WikiLink, but prefix it with a colon.

For example, this link to the Help Category index page was created with the text [[:Category:Wiki Help|this link to the Help Category index page]].

Disambiguation and Wiki Templates

A template exists for disambiguation on the dragon wiki. This becomes necessary when two different items share a common name, for example the Cathedral building on Limbo and the Cathedral (sim). The template that has been created produces the "This page refers to" text and standard disambiguation image and should be added to the top of each page that shares the common name. The template is referenced like this:

{{disambiguate|the Cathedral Sim|Cathedral}}

The curly braces tell the WikiMedia engine to look for a template called "disambiguate" and the following parts separated by the vertical bar, or pipe symbol, are text descriptions called parameters that are substituted into the template. The first parameter is a description of the contents of the current page, and the second parameter is the name of the item that is being disambiguated. The example above produces the following text:

This page refers to the Cathedral Sim. For other uses of "Cathedral", see Cathedral (disambiguation).

There is no template for the actual disambiguation page itself; it is up to the editor to create that for themselves.

Useful Wiki Editing Resources

• MediaWiki Formatting Help
• Wikipedia's Quick Guide
• Wikipedia's Cheatsheet