The current instructions on how to use the wiki are found when you try to edit a page.

They are also available on the EditPageHelp wiki page:

http://wiki.jboss.org/wiki/Wiki.jsp?page=EditPageHelp

Also the SystemInfo page describes the version of JSP Wiki that is being used: 2.1.53-cvs

We should point out the difference between the 2 wikis that are used; JBoss Wiki and JSP Wiki. This page points out that the JSPWiki implementation went live on 27th February 2004.

There is a documentation license that applies to all information submitted to the wiki:

http://wiki.jboss.org/wiki/Wiki.jsp?page=DocumentationLicense

This should be pointed out in the Wiki section of the Governance model.

There are currently some pages on the JSPWiki that explain what the wiki is and how it should be used:

Watching the JBoss Wiki with an RSS reader

All About Wikis page

Wiki Etiquette

The current versions of our wikis are:

• JSPWiki (Version 2.1.53-cvs)

• JBoss Wiki (Version 1.0beta2)

New Design

Wikis are an essential tool for online collaboration, allowing rapid growth and centralization of information created by the community. Due to their popularity and usefulness many different wiki products are now available with an ever increasing number of features.

The wiki product that jboss.org uses is called JSPWiki and you can find the main page at http://wiki.jboss.org.

JSPWiki was chosen at the start of 2004 for a number of reasons including:

• It was open source

• It was written in Java using standard J2EE components

• It was actively developed

• It was easy to install and use 

Since going live on 27th February 2004 over 2500 pages have been created, providing information on a wide range of JBoss projects.

Note: Care must be taken not to confuse this wiki, commonly referred to as the JBoss Wiki, with a JBoss project of the same name. The JBoss Wiki project is focussed on the development of a wiki portlet (based on JSPWiki) for use in JBoss Portal or any other standards-based portal. The ambiguity in the name is unfortunate, especially since the JBoss.ORG team use the JBoss Wiki portlet for their own wiki located at http://labs.jboss.com/wiki. This wiki contains information regarding the ongoing development of the jboss.org site.

To avoid confusion, any references to JBoss Wiki from this point onwards will refer to the wiki located at http://wiki.jboss.org.

Using the wiki

Reading the wiki is as simple as pointing your browser to the main page and clicking on the links you are interested in. To keep the layout as logical as possible, users are encouraged to search for appropriate pages to place links to any new content. For example if a user creates a new page with a tip on configuring JBoss Security they should place a link on the JBoss Security page or subpages, instead of on the Main page.

Anyone can read the wiki anonymously but if you wish to create or edit a page then you first need to login to your jboss.org account. If you don't have a jboss.org account then you can register for one by clicking on the Register link at the top of the page. Registration is free and only takes a few moments. This requirement helps to prevent spam and allows you to track your changes over time by recording your username and the current date and time for each change made.

Documentation License

To accept and publish wiki contributions from the community, jboss.org requires that authors observe a simple documentation license that covers the terms and conditions of use. The text of this license is as follows:

All authors submitting documentation to the JBoss Wiki give Red Hat a non-exclusive right to use, reproduce, publish or republish the documentation.

Features

Along the top of each wiki page are a number of links that provide useful functionality:

• Home - takes you to the main wiki page.

• About - gives a brief overview of the JBoss Wiki.

• Search - allows you to search the wiki and the jboss.org site for relevant pages.

• Changes - lists all of the changes made to the wiki in the last 30 days (or since the wiki began if requested).

• Unused Pages - lists all of the pages that are not linked to (and therefore hard to find).

• Undefined Pages - lists all of the links to wiki pages that have not yet been created.

• Index - presents an index of all the wiki pages.

• License - displays the documentation license that applies to all wiki contributions.

Leaving a trail

As you browse through the wiki the last 10 pages that you have visited are displayed in a breadcrumb trail beneath the Page title, separated by a | symbol:

Your trail: SandBox | WikiVariables | TextFormattingRules | WikiEtiquette | WikiName | Main | MailingLists | JBossHelp | BadPostFAQ | BadPosts

If you revisit a page then it will appear in the list again at the end once you move somewhere else. Hitting the backwards and forwards buttons on your browser causes the trail to adjust accordingly.

Note: This feature requires the user's browser to allow cookies. If cookies are disabled then no trail is generated.

Creating a page

There are 2 ways to create a new page:

1. Enter a URL into your browser of the form http://wiki.jboss.org/wiki/Wiki.jsp?page=<name> where <name> is the name of your new page. If a page with that name does not exist then you will be given the option to create it. This method allows you to create pages that are not linked to.

2. Edit an existing page and enter a link to the page you wish to create. This link will initially be displayed with a question mark next to it to indicate that the page does not yet exist. Clicking on the question mark allows you to create the new page.

Creating links to pages

Traditionally links to pages in wikis are created using words entered in Camel Case. Camel Case is a way of writing multiple words where spaces between the words are removed and the first letter of each word is capitalized. For example the words 'security tips and tricks' would be written in Camel Case as 'SecurityTipsAndTricks'. By default JSPWiki does not treat words entered in Camel Case as links to new pages,  however the wiki administrator can turn this feature on if required. To see whether Camel Case links are used, go to the SystemInfo page and look at the properties inside the Usability table.

Sometimes you may enter a word that happens to match the Camel Case pattern but does not represent a link, for example EclipseCon (the title of the annual Eclipse Conference). In these situations you can prepend the word with a tilde (~) character to tell the wiki that it isn't a link, i.e. ~EclipseCon.

If you prefer you may also specify links using square brackets like this:

In this case the name of the page being linked to is generated by removing any non-alphanumeric characters (except _ and .) and converting the remaining words to Camel Case. For example generates a link to a page called JohnsPage.

If you want to have a link using normal text, with spaces and punctuation, then you can use the following format:

John's page

On the left of the | symbol is the link text and on the right is the name of the page being linked to.

Finally, if you want to make links to external wikis such as wikipedia then you can use the following format:

JBoss definition

For this to work the wiki must be set up with an InterWiki link so that the word Wikipedia is automatically replaced with http://www.wikipedia.com/wiki/. The resulting link therefore becomes http://www.wikipedia.com/wiki/JBoss.

You can see all of the available InterWiki links from the SystemInfo page. If you need an additional InterWiki link setup then please contact the wiki administrator (bob.mcwhirter@jboss.org).

Editing a page

To edit a wiki page you just need to click on the 'Edit this page' link found at the top and bottom of each page. You can then enter text just like writing an email using return to start a new paragraph. Once you have finished you can hit the 'Preview' button to check your changes or the 'Cancel' button to abandon them. If you are happy with how your changes look in the preview page then you can go ahead and save them.

Note: The Save button on the Preview page does not work at the moment so you need to hit the back button of your browser and use the Save button from the Edit page instead.

If you want to format your text to make it more readable then there are a number of special characters you can use. These characters form the wiki markup language.

Headings

To create a heading you can prepend words with one, two or three exclamation marks. The more exclamation marks that you have then the bigger the heading appears.

Bold text

Use double underscores immediately before and after text that you want to appear in bold.

Italic text

Use 2 single-quotes immediately before and after the text that you want in italics.

Monospaced font

Use double curly braces immediately before and after text that you want to appear in monospaced font.

Code blocks

To create code blocks use triple curly braces immediately before and after the text that represents code.

Bullet points

To make a list of bullet points place an asterisk () at the start of each line. Use multiple asterisks () for deeper indentations.

Numbered lists

To make a numbered list place a hash symbol () at the start of each line. Use multiple hashes () for deeper indentations.

Tables

To create tables use bars to define the columns. For table headings use double bars.

Ruler

To create a horizontal ruler use 4 consecutive dashes. Additional dashes will be ignored.

Line break

To force a line break use a double backslash.

Definitions & Comments

To make a definition for a term you can use a semi-colon followed by the term and then a colon followed by the definition. This markup can also be used to make indented comments if you simply leave the term part empty.

You can see all of the Text Formatting rules used by JSPWiki on the JSPWiki site.

SandBox

If you want to experiment with any of the wiki markup characters then please use the Sandbox page. This prevents multiple test pages from being created and helps to keep the wiki well organized.

Variables

The wiki contains a number of variables relating to configuration and usage. They contain information such as which image types can be displayed in pages or how many pages there are in total. To insert these variables into your text, you need to create a link of the form [{$variablename}:

Note that variable names are case-insensitive. For example "pagename" is the same as "paGeNamE" and "PageName".

You can see the full list of available variables at WikiVariables.

Attachments

If you have an image, video, log file or any other kind of file that you wish to refer to from your wiki page then you can upload it as an attachment. Simply click on the 'Attach file...' link at the bottom of the page and follow the instructions given in the popup window. If a popup window does not appear then make sure you have JavaScript and popups enabled in your browser.

Each attachment will appear in a list at the bottom of the page together with a paperclip icon and its size in bytes. Clicking on the paperclip takes you to a page displaying a 'Page revision history' table. From here you can download previous versions by clicking on a number in the version column or upload a new version using the 'Browse...' and 'Update' buttons. When uploading a new version the name of the file being uploaded does not have to match the attachment name (which is always the original filename).

You can make as many attachments to a wiki page as you like. To refer to them from the same page you simply have to create a link using the attachment name, for example:

Note: If you have a wiki page with the same name as an attachment then the attachment takes precedence.

If you wish to refer to an attachment on a different page then you need to specify the page name as well:

Images

Sometimes you may want to display an image as part of your wiki page. As the saying goes 'A picture is worth a thousand words!'. To do this you first need to check that the wiki has been configured to display your image type (.png, .jpg, etc...). A list of all supported types can be seen on the SystemInfo page in the main table.

Providing your image type is supported you then need to make it available on the internet. If it is already available then you simply reference it with a link:

http://www.jboss.com/themes/jbosstheme/img/logo.gif

If it is not available then you may want to attach it to the page and reference it as an attachment:

If you specify link text then it becomes the ALT text for people who can't or don't want to view images:

JBoss Logo

Deleting a page

Occasionally pages need to be deleted in order to remove outdated or reorganized information, tests made by people to see the effects of wiki markup or inappropriate content. To delete a page you need to include a link at the beginning, followed by a comment describing the reasons why. For example:

this page has been moved to

An administrator will periodically search for these links and manually perform the deletion. Users are prevented from deleting pages themselves to prevent mistakes and potential misuse. If you see a page marked for deletion and do not agree with the reasons why then you are free to provide another solution, such as refactoring the content, and remove the link.

Viewing previous versions of a page

You can see all the previous versions of a page by clicking on the 'More Info...' link at the bottom. This reveals a 'Page revision history' table detailing the date and time changes occurred along with the authors who made them. Clicking on entries in the Date and 'Changes from previous' columns allows you to see the changes made between different versions. Clicking on an entry in the Version column allows you to see the page at that version. If necessary, you can then choose to restore the previous version by clicking on the 'Restore this version' link.

Viewing the last changes made

At the bottom of each wiki page is a line telling you the date and time the page was last changed and who it was changed by. If you are interested, you can see details of the changes by clicking on the date and time.

Watching for wiki changes using RSS

If you want to keep up with the latest changes made, you can subscribe to the RSS feed located at:

http://jboss.org/wikirss/index.html

The feed is updated periodically according to the time shown in seconds in the RichSiteSummary table on the SystemInfo page.

Note: This feature is currently broken.

Wiki Etiquette

When editing pages please keep the following rules in mind:

General

• Be gentle - don't be rude or offensive.

• Write in a way that is easy to understand and avoid local slang or phrases. Many of those who will read your text may not have English as their first language.

• Don't delete other people's contributions (unless you know what you are doing).

• Don't use too many acronyms (or at least, have a page explaining them).

• Avoid the "click here" phrase. For example don't write "[Click here| ] for more info about etiquette" but use "More info about WikiEtiquette". Follow the same approach for external links as well.

• Only contribute original material. Links are fine, but don't cut-and-paste from copyrighted material.

• Correcting typos is quite okay - in fact it's a very good habit since it makes the wiki pages more readable.

• Use absolute date references. You never know when someone will be reading your content in the future. For example use "As of December 2005, we are the only competitor in this market." instead of "As of now, we are the only...".

• Avoid self-referencing pronouns. Instead of "I think the best method for..." try "Some think the best method for...". You are not the only author of a page over time.

About comments

• When multiple comments appear on a page it is preferred that you sign your comments with your name (or handle). This makes it obvious to readers who is saying what. It is common to prepend your signature with '', for example " Janne Jalkanen". While you're at it, you are free to create your own wikipage and tell us about yourself .

• Another good way to identify yourself is to put your name first, for example "Janne Jalkanen : I'd like to say that..." or use the third person, for example "Andrew Cates agrees.".

• Think before you comment. The wiki is not a high-speed conversation board and it's not a news server either. What you say will stay here for a long time for everyone to see and comment on.

Creating pages

• A good page name (also known as a WikiName) is short and descriptive. If the name is logical and easy then many more people will link to it.

• Although you can take a whole sentence and crunch it up to make a page name, it is better style to restrain it to at most 5 words.

• Try to use page names like you would use chapter titles in a book.

• The wiki allows you to create pages with a single word as a name, but try to use at least two words - we don't want to exhaust the name space .

• Double-check page names for typos otherwise someone will create a misnamed page! Misnamed pages are bad, since they require more effort to link to than pages with correct names.

• Please try to check whether a page containing similar content already exists before creating a new page. Duplicate pages cause confusion and increase navigation problems enormously.

Refactoring pages

Refactoring is the process where you sum up a page, potentially shorten it and generally make it more accessible. Anyone who feels up to it may go ahead, but we suggest that you leave it up to frequent (experienced) visitors.

• Be objective - both pros and cons should be represented correctly.

• Be careful with signed contributions - don't change their meaning.

• Give credit where credit is due.

• Use 3rd person or plural instead of 1st person singular in your summary.

( Thanks to JSPWiki for the initial text!! )