Wiki

THL Toolbox > Workflow Issues > Sakai Collaborative Worksite Technology > WIKI

WIKI Manual for Sakai Collaborative Worksite Technology

Contributor(s): David Germano.

Introduction

This is for collaborative editing of pages and content. A Wiki is a kind of collaborative website in which multiple users can add and change the content. Each page is in effect a type of electronic blackboard, where any user can work on that document - erase sections, revise text, or add new text. If two users happen to make revisions at the same time, the program will alert the last person to save that someone has made changes while they were working. That person then should review the changes, and be responsible for integrating the content. If they reject someone else?s changes, it should be for good reason and they should contact the person to let them know that happened.

The Sakai Wiki Tool gives users the ability to create a Wiki that is dedicated to a particular course or project site. Members of that site can monitor, update and edit the content of the wiki. The Wiki Tool also allows users to add images, link wiki pages to other documents, and view the change history of the wiki. The website owner can control what permissions the members have, including access, reading, writing, editing, etc. Wiki is a Sakai provisional tool -- it is not a core component of Sakai Releases, but it is relatively well-developed and is in use at multiple Sakai Installations.

It is VERY important to design a Wiki well in terms of what the home page has on it, and how navigation in general is effected. The principles should be to make the first page as useful as possible, and stay away from many levels of embeddedness where you have Wiki pages containing tables of contents for other pages, which in turn contain more, and so forth. The more people have to drill down the less likely they will. Thus try to avoid top level pages with little content other than more links. Thank about what content/pages are most frequently used, and put them as high as possible in the hierarchy of Wiki pages. Try to avoid pages that just have a simple list of Wiki page links. Instead, choose the most important/commonly consulted Wiki page being linked to, and instead put it right there on the first page under a h2 header, following the list of links to other pages. When there are repetitively structured sub-nodes, consider making a standardized set of "quicklinks" at the top of each wiki page so you can easily switch back and forth between various sub-nodes of a given section.

Formatting in WIKIs

WIKI formatting is so extensive, that this is a separate page. So please click on the rubric above to see details.

Breadcrumbs

One of the advantages of Wikis is that each Wiki page is entirely autonomous and has no intrinsic connection to any other Wiki page. However, this can be a problem when you have a clear set of relationships in mind for a set of Wiki pages, as well as for navigation through a number of related Wiki pages. Within THL, we have resolved this in two ways. Firstly, we publish a table of contents to the first and possibly second level of a hiearchy of Wiki pages. Secondly, we add "breadcrumbs" to our Wiki pages that express the relationship of a given Wiki page to other Wiki pages that we intend it to be "contained" within in terms of a hierarchy of Wiki pages. Breadcrumbs are a term used to express a series of hyperlinks that show the way in which one has arrived at the present page. For example, Collections > Art > Modern > Oil Painting. Such breadcrumbs are used to facilitate navigation, so that users can easily retrace their steps and get back to an earlier page they were consulting.

In the Wikis, we insert breadcrumbs at the top line of each Wiki page using a h6 header. We start with the home page which is given a relevant label, and then continue to the present page, which itself is not hyperlinked:

Thus: h6 [Ecotourism | home] > [Wilderness] > Hot Climates.

When a group of Wiki pages corresponds to a top level in a right hand side secondary navigation in THL, the "home" breadcrumb should correspond directly to that top level in name, rather than correspond to the overall home for the whole set of Wikis. An exception is when the secondary navigation is not nested, such as in the Toolbox, and you want to have all breadcrumbs go back to the root home page for that whole set of Wiki pages.

Add a new WIKI page

You can make as many WIKI pages as you want. The way you make a new WIKI page is you go to any given WIKI page. Click EDIT on the top to get an editing view of that page. Then add a link to the new page that has the name of the page with square brackets around it - [Workshop plans], for example. Then save your changes, and that will appear as a link to the new WIKI page.

One very important to keep in mind is that you can NEVER have a WIKI page which has the same name as another WIKI page in the repository you are working. This is very useful if you want to have multiple links to the same document - just add the name of the document with brackets around it to whatever WIKI page you want it to be linked to from. However, a limit of this is that you might want to create say workplans for multiple staff, each with subdocuments that have the same titles - "This Week", "This Month", etc. However you can?t do that since you can only have a document or subdocument with unique titles. Thus you simply have to plan around this, such as adding unique terms, so you have "This Week (Bill)", vs. "This Week (Sue)". Of course you might give a document the same title as an extant document by mistake. Thus after creating new links, check visually. Usually when you create a new link, WIKI will put a "?" after the link to indicate the document being linked to has not yet been created. Once you click on the link and begin editing the resulting document, the "?" will go away. If there is no "?", it means the title is already in use and a corresponding document exists.

This also means that when you rename a page, whatever the page was linked to in terms of content is unlinked. Thus you CANNOT rename pages. Or if you need to, you must first copy the corresponding document, and then after renaming the page, follow its link and paste the old content into the new page. If you do this by accident, don?t worry - you can still find the old pages under "recently modified" on the WIKI home page and retrieve the document. Notice if you cut and paste text from a word processor into a WIKI page, be careful to make sure the whole text is saved in the WIKI - if there is a strange symbol like a r with a circle around it, the WIKI will often delete all text after it

Changing default "new page" content

When you first click on a new WIKI page, it provides default textual content saying that the page doesn't exist. THL worksites have changed this to read, "This page is newly created, and needs to be edited. Begin editing by clicking on the Edit button below. Erase these words, and write your own?". Thus when you first create a new worksite, go to the WIKI and type in "default_template" in the search box. Then click on the result, and edit it - replace its content with the words above. From then on, all new WIKI pages will have that sentence, which is somewhat less forbidding than the more extensive default content that is otherwise used. If this doesn't work, you can instead just search the home page in the WIKI for "default_template" using Firefox - Ctrl F and you get at the bottom of your screen a Find: text entry box. Just type in the word default_template and hit "next". That will search through the list of recently changed files in the WIKI home page and show you the default_template.

The default template is best changed along the following model to insert breadcrumbs, as well as a standard header 1 title:

h6 [Toolbox |home]> Insert Rest of Breadcrumbs Here

h1 insert Name of Subject Here Technical Documentation from the [Toolbox |home]

Do not use the header 1 style again in the document, but rather subsections should be header 2s, while sub-subsections are headers 3, and so on.

You might also want to temporarily change the default_template if you are mass creating WIKI pages in a work session all of which have a similar header.

Here is a sample default page:

h6 [Contemporary Tibetans Biographies | /home] > INSERT BREADCRUMBS

h1 INSERT WIKI PAGE TITLE

This page has been automatically generated since you have created a new WIKI page. If you want to change the content that gets automatically generated each time you make a new WIKI page, just edit the [default_template]. However, only do that if you have a good reason.

To edit, just click on the word "Edit" above, make your changes, and then click on the "Save" button below when you are done. The first step should be to add the breadcrumbs in the first line, insert a specific title, delete these words, and add your own content.

When adding breadcrumbs (a sequential list of the levels containing this WIKI page), remember to use the specific name of the WIKI pages leading to this page, surround each with brackets, and separate them with ">". An easy way to do this is to go right above the "Edit" line, and just copy the breadcrumbs after Home >, and then put brackets around the names. The utility of the breadcrumbs is that it is then easy to see just where this page fits in the overall WIKI, and easy to navigate back to other levels.

To the upper right you can show a "help sidebar" with various shortcuts for creating formatting in WIKI pages. Also just above this editing box you will see short hand controls for bold, italic, etc. Just highlight the word you want to apply these to, and then click on the corresponding function. To create a link to a Web page, highlight the text, and click on "external link" and then substitute in your URL for the URL given there for google.

If you want to have a different type of default content generated for each new WIKI page, just edit the [default_template] which determines the content you see for each new WIKI page.

Linking to WIKI pages

Within a given WIKI/Worksite, to link to a WIKI page just surround the WIKI page name with brackets. If you want to label it in that context in a way other than simply its name, then [Label | Actual WIKI page name]. If you want to link to a WIKI page i na wholly different WIKI , i.e. a different worksite, use the language of [Label | Actual WIKI global name obtained by looking it up under INFO view of that WIKI page].

Creating and Revising WIKI Hierarchies

One important to realize is that in WIKIs, there is no formal distinction between folders and documents. The same entity servers both functions. Thus you can use a WIKI to create a nested scheme for storing documents, but the hierarchy of "buckets" where documents are stored is created through linked documents, rather than a series of folders or directories. Thus you create one document that is the top level, and then you link to other documents which represent level two. Then those documents in turn can link to other documents, which are level three and so on.

This means that it is very easy to change your scheme, since you can at any point simply cut and paste links to documents to create a new scheme. Thus if you find the navigation clumsy as a site grows, a few minutes of cutting and pasting can easily produce a new structure with all the documents located just where you want them in the new structure. This easy of expressing and revising hierarchies is one of the great things about WIKI technology.

Attachments

In a WIKI, it is possible to add an attachment, so that if you have a word document and aren't ready yet to migrate it into WIKI, just attach it in the right place within the WIKI. To make an attachment, select the 'edit' button to edit the page. Then select the 'resource link' button. This will take you to your Resources folder. You can either click 'select' to attach an existing resource on your worksite or click 'add new' to attach a new resource from your computer. When you have chosen your image, click 'finish'.Your image will be inserted into your page. Attachments are stored in Resources but you don't need to have the Resources tool enabled to add attachments. You can link to any sort of resource that you create in Resources so, any type of file you upload, or an HTML file or text file you create. If you update the file in Resources, your attachment will automatically be updated too.

Email Notification of Changes in WIkis

You may set the Wiki email notification preference to receive an email notice when a wiki page is changed. This must be set for each wiki page about which you wish to be notified of changes. To set email notification for a wiki page,

In the gray bar at the top of a wiki page, click the Info link.
Scroll down to find the Notification Preferences section.
Click the link to Edit Notification for site/blah.
Select the option to Send me each notification separately or another option of your choice (Send me one email per day, do not send me notifications, I do not have a preference).
Click Save to set the option or Cancel to quit.

Making comments on Wikis

Wiki pages now display a Comment link at the bottom of the page to allow others to review and comment on page content when they don't wish to revise the wiki page itself. To add a comment,

Click the Comment link at the bottom of the wiki page. A New Comment box appears.
Type your comments into the comment box..
Click Save. Your comment will appear at the bottom of the page along with the date and time you posted the comment.

To edit a comment,

Click on the Edit link next to an existing comment.
Enter your changes into the Edit Comment box.
Click Save. Your modified comment will appear on a new version of the comment page.
When you return to the commented wiki page, your modified comment will appear at the bottom.

Hint: Use the breadcrumb navigation at the top of the page to navigate back to the starting wiki page.

To comment on a comment,
Click on the Comment link next to an existing comment.
Type your comments into the comment box.
Click Save. Your new comment will appear on a new comment page.
When you return to the commented wiki page, your new comment will appear at the bottom.

Permissions

Wiki has two levels of permissions at site level and at page level. Site level permissions are the default permissions for all pages. However, permissions can be changed for individual pages. For example, you can alter permissions so that wiki is editable by everyone, apart from one page which can only be edited by maintainers. To alter the site level permissions, click on "INFO" for any WIKI page, and then down next to the SAVE button on that page, it says "you may edit site permissions". Click on that and it will show you the default permissions for all pages within that worksite.

There are 5 levels of permission within Wiki:

Wiki read (read pages)
Wiki create (create new pages; update must be enabled to allow this)
Wiki update (edit pages)
Wiki admin (alter site permissions)
Wiki super-admin

There are four types of people for which you can specify different settings for each of the above: Administrator, Member, Observer, Owner. Generally, you want members to be able to create and update, but not do admin. The most typical problem is to have pages set so that members cannot update. However if you want to preserve a WIKI from changes, then that would be the appropriate settings.

Remember that permissions cascade downwards you cannot update a page if you cannot read it, so it makes no sense to enable 'update' but dis-enable 'read'. If you enabled 'create' or 'update', Wiki will assume that you want 'read' permission enabled as well.

Sakai roles are not automatically mapped to WIKIroles in order to allow the tool to be used in a more flexible way. We recommend the following ways of mapping Sakai permissions onto Wiki permissions.

Default - using the WIKI as a traditional WIKI tool

With these permissions, all users can edit the WIKI. This would allow collaborative drafting of documents, for example. This is the default setting for permissions.

Read	Create	Update	Admin	Super
Access	yes	yes	yes
Maintain	yes	yes	yes	yes	yes

Using the WIKI as a simple content management system

With these permissions, only maintain users can edit the WIKI. Access users can only read pages. This allows it to be used as a simple content management system.

Read	Create	Update	Admin	Super
Access	yes
Maintain	yes	yes	yes	yes	yes

Page-level permissions

Page-level permissions apply to that page only. For example, you can alter permissions so that wiki is editable by everyone, apart from one page which can only be edited by maintainers.

To alter page-level permissions, select 'info'. Tick and un-tick the boxes below the permissions to alter the permissions settings. Because permissions cascade downwards, this may not always have the effect that you imagine. For example, if 'update' is enabled for a role, you cannot dis-enable 'read' for that role, because users must be able to read a page to update it.

The 'create' permission is not applicable to page-level permissions and can only be altered at site level.

Site-level permissions

Site level permissions are the default permissions for all pages. To alter site-level permissions, select 'info' and then select 'edit site permissions'. Tick and un-tick the boxes to switch permissions on and off.

Tables

Be careful with making tables - if you insert a table from the "table" link above the editing window, it inserts markup with a line at the beginning of each line, which creates an empty column on the far left - instead cut and paste the sample markup from the bottom of the HELP column which is cleaner. Basically, the first column should NOT have a vertica line in front of it. The first row should give the column names, or labels - like Name, Address, Phone, etc.

I like to put the item in the first column in each row in bold face to give a clearer structure to the table in terms of formatting. It also makes the edit mode easier to read since the underscores marking bold make clear where rows start.

If you already have a WORD table that you want to cut and paste into the WIKI, a few simple steps will make it an easy conversion. First, select the table: Table: Select Table. Then change it to text with Table: Convert: Table to text. Click on "Other" and cut and paste the vertical line there in. This will convert the Table to text with a vertical line at the end of each column. With a little clean up, this can then be cut and paste into the WIKI table. Also note that you can't have carriage returns within a WIKI table cell. So if your old table has cells with carriage returns inside, delete them and convert it to semi-colons, periods, or whatever else works for you.

Importing WIKIs from other Sakai Worksites

It is possible to import an existing wiki from another worksite in the upgraded version of Sakai in the standalone Collab environment. You are able to import an entire wiki from another worksite even after a new worksite is created. You don't have to do it at creation time. However, it appears that importing a wiki from one site to another will overwrite any pages sharing a name (like Home). All imported pages will show the author as the person who imported them as well as setting the creation date to the import date, so not all data is preserved.

In the site to which you want import something, go to the SITE INFO tab. On the top list of options, you will see "import". That will give you a list of all the worksits to which you belong. Select the one(s) you want to import from. Then it will ask you what you want to import - the options are Announcement, Resource, Schedule, WIKI. Select the one you want, and then hit continue.

For the WIKI, it should then show the imported WIKI in the WIKI tab. However, I am not having success with that. If I put the name of a WIKI document from the imported site, it will work so clearly the importation works - it just doesn’t automatically show in the WIKI unless I manually insert the name(s) of the files I want. Its an easy fix - if you want all of the WIKI to show, just copy and paste in the root page of the original WIKI; if you want only some of that WIKI, then add links to whatever node(s) you want.

Viewing one worksite's WIKI in another worksite

It is possible to view WIKIs across worksites. The protocol is to enclose the whole thing in brackets like you would with a new WIKI link. However you first put the label you want to appear, then a vertical line, and then the "global name" of the other worksite's WIKI. You can find the global name of a WIKI by clicking on INFO for that WIKI, and then paging down to where it says "global name". It looks something like "/site/79dd35b8-bf8f-4332-00b7-35794ba5301e/numbered lists". This allows you to both view and edit the WIKI in question from the new worksite, even though its permanent home remains in the other Worksite. You do not need to enable "public update" on the source WIKI for this.

Publishing WIKIs for public

Worksite WIKIs can be shown via URL to the public. You have to click on INFO for that WIKI, and then set the permission settings so that the public can "view" the pages. Then hit SAVE. Then go further down that INFO page in the feeds section where it says "Public View". Click on that, and it will open up a second window with the public view of the WIKI. Copy the URL from the browser address line and you have it. This public URL can also be used whether or not you have activated public view, but only by people within a worksite after logging in.

There are some limitations in the public view. The WIKI page’s header does occur. However it appears in a grayed out font and small. Thus it too small and washed out, making the page look strange. In addition, the public view lacks any breadcrumbs, or the simple home link. This makes navigation quite hard. Is it possible to expose in public.

Please note it has settings for the public being able to "update" the page, but these do not work. That will only work if you want to have a link to your add a link to your publicly editable wiki page (that you provide to them) to their wiki that they can view and edit your wiki page from within their own worksite wiki. It doesn't make the "Public View" URL editable. But this seems irrelevant since within worksites its better to use the other protocol (see above) to just incorporate the other worksite's WIKI into the second worksite.

View Only

In the source wiki, set the pages that you want to be Public Readable:

Click on Info for each source page to be shared.
Check the box to Enable Public Read.
Click the Save button.
Copy the Global Name URL to paste into the target wiki new page link.

B. In the target wiki, add a link to one or more pages in the source wiki:

Click Edit to add a link on a target wiki page to the source wiki page.
Use the bracket syntax to create a new page that points to an existing page in the source wiki, similar to [Target Wiki Page Title|Source Wiki Global Name URL] <= (paste the copied Global Name URL here).
Save the edit.
Click on the new page link to view the page being served from the source wiki.

View and Edit Shared Wiki Pages

Follow same steps as above, except in step A2, also check the box to Enable Public Update. Pages in the source wiki will then be editable from within the target wiki. These edits will likewise appear in the source wiki.

Note: If a participant in the source worksite wiki has update permissions in that wiki and is also a member of the target worksite, they will be able to edit the source wiki pages from within the target wiki regardless of whether the Public Update permissions have been enabled in the source wiki.

Deleting WIKI Pages

Currently there is no way to delete a wiki page once it has been created. According to Andres Montano, in general for wiki pages you should be able to search for all orphan pages and then kill them all. We are looking into this.

Tips for Migrating Word Text into the Wiki

Because this Wiki has a cumbersome editorial interface, many people find it easier to create a complex document in a word processor first, and then cut and paste it into the Wiki page. However, the cut and paste can involve quite a lot of clean up. This section provides some tips as to how to reduce the extent of clean up.

The Wiki requires an empty line between paragraphs. Thus if in Word you are using line spacing to create spaces between paragraphs rather than actually manually inserting a line, upon import into the Wiki it will be lost. If you instead create the document in Word with empty lines manually inserted between paragraphs by hitting RETURN twice, you won't have to clean this up in the Wiki.

Tables are one of the most cumbersome things in the Wiki, but are easy to create in Word and import. Create the table, and then in Word, choose Table > Convert > Table to Text. Then change the character that will be used to separate items in different cells with a |, which is what the Wiki uses for separating columns. Then put {table} on the line above and below the table, and it will format perfectly in the Wiki upon cutting and pasting it in.

Make your list that you want bulleted. Then in Word, format as a bulleted list – Format > Bullets and Numbering. Choose one of the types of bullets, and then click on customize. Put it on the font you usually use, and select asterisk. Then cut and paste into the Wiki page. It will cut and paste as asterisk with a lot of spaces after it. Cut and paste it back into Word and do a global search and replace of the asterisk with spaces to asterisk with one space. Cut and paste back into the Wiki page and it should be perfect. Obviously that is a lot of steps so it only makes sense if you have a long bulleted list.