How to contribute

Contributing material to the Knowledge Base Wiki

In this article, the basic procedures for authoring content for the KB Wiki are described. These notes are intended for those KB Wiki users who have previously submitted a request to contribute a KB Wiki article (eg, for an AC, UFR or DNS). The procedure for requesting new content is not described here but is outlined elsewhere on this site, please view the Library. Therefore, the basic assumption is that a new KB Wiki article has already been set up with individual links between the article pages in place. The notes contained here are intended to help the contributor to populate these pages with the basic technical content he or she wishes to add.

The information on this page is also of interest to visitors who wish to leave short comments on the Discussion page of each KB Wiki article. It is possible for a Discussion page to become a substantial document in its own right and some basic principles and guidelines described here may be helpful in maintaining a well-organised and presentable Discussion page.

We assume that the contributor is not an expert in HTML or web design but has some experience of viewing Wikis and similar online applications.

General Advice

Before editing Wiki pages, please bear in mind the following advice.

• Keep it brief! Each article is intended to be the size of typical journal article. The Description, Evaluation etc pages within an AC or UFR should be no more than 4-6 screen-fulls of text at most. If your reader is scrolling up and down a very long page to get to the text he or she requires then they will quickly get tired and frustrated. Therefore, you should aim to have a page with a convenient length that is not too long for the average reader.

• Keep to the standard article format. All significant content in the article should be restricted to the pages that have been set up on your behalf by the Wiki Editorial team. Please don't add any extra pages on the Wiki and reference them from your article. It is desirable to keep to a standard article layout for the sake of readability and a common style.

• If possible, add equations in LaTex format. LaTex is an excellent way of ensuring that the equations are presentable and can be conveniently changed if there are any errors or inconsistencies in notation. LaTex should be preferred to equation images wherever it is practical to do so!

• Resist using HTML. Contributors should try to minimise the use of HTML as much as possible. Use Wiki text format for things like tables, lists, sub-section headings instead. HTML is reserved for use by site administrators for top-level elements in the Wiki but in general for articles they should be considered to be forbidden. With many rules there are always exceptions and you may be forced to use span links in your text in order to identify a particular section of a page to jump to from another page (described below). This is one of a few exceptions that are forgiven at this time...

• HTML Converters All submissions have to be in Mediawiki Text format. If you wish to submit a word document you will have to convert your word document first, by using a HTML converter, into the desired MediaWiki Text. Once this has been achieved a simple copy and paste is all that is required. To do this firstly load the word doc file into OpenOffice and save it as a HTML file. Next, load the HTML file into a browser, open a page source window, and paste the HTML into the web-based converter found here. Select the correct wiki format which must be MediaWiki Text and press the button. Then simply paste the converter output into the wiki editor when making your contribution and clean up by hand. There may be problems with some accented characters, just delete them from the converter output before pasting into the wiki editor and fix later.

• Resist using Style elements! Using individual style attributes on WikiText elements often makes the wiki text difficult to edit or read. As with HTML they are reserved for the KB Wiki Team team only and should not be used within articles. If you absolutely need them then contact us and we will seek alternatives where possible.

• Don't attempt to use JavaScript, Flash or similar items These cannot be added to a page for security reasons so please don't attempt to add them.

A Special Note on Data Files

At this time it is the standard practice in the KB Wiki to keep raw numerical data files in a separate site away from the KB Wiki content itself. Links to this data should be inserted into the document.

Therefore, the contributor has three options:

• to host the data him or her self in his own domain, or
• to provide the data files to KB Wiki for administration on his or her behalf. For ACs and UFRs, check Data Formats and Submission.
• for Direct Numerical Simulation (DNS) data please check high fidelity data storage guidance

If you wish your data to be managed by the KB Wiki, then these files need to be uploaded by arrangement with the KB Wiki Team. After this is done, the administrator should provide the necessary link information in order to enable you to generate the necessary links in your text.

Basic Steps

This section gives a top-level introduction to the basic steps in editing a KB Wiki page.

Entering Edit mode

The user first goes to the page he or she wishes to edit.

Unlike systems such as Microsoft Word etc, the user must enter an 'edit mode' in order to make changes to a KB Wiki page. To enter editing mode, click on the 'edit' tab link at the top of the page:

The following image shows the page in editing mode. Note that any new text, including WikiText expressions, is confined to the editing area of the page.

It is also possible to edit particular sections within a page by clicking on the 'Edit' link that can be found at the top of each section. This is sometimes more convenient if the link to the Wiki is slow, the page is rather large and you only wish to modify a part of it, or if you are using a very slow client machine. An example of an edit link is given below:

Entering Basic Content

Having entered edit mode, the user can now enter the text of his or her article in the Edit area shown above. This section describes how simple content can be added and saved. 'Simple Content' includes paragraphs, sections and lists.

'Ordinary text', should be entered at the location of the cursor on the page: just scroll down to the part of the page to be edited, position the cursor and type in the text.

Paragraphs in the text are separated by a blank line. Lists of un-numbered items (eg, lists of bullets) can be added by using the asterisks for each item, as shown in the following WikiText example. This shows two paragraphs followed by a list of un-numbered list points.

This is the first paragraph.

Here is a second paragraph.

* Item 1
* Item 2
** Subitem of Item 2
*** Sub-subitem of Item 2
* Item 3
etc

The above list is rendered as:

• Item 1
• Item 2
  • Subitem of Item 2
    • Sub-subitem of Item 2
• Item 3

Numbered items are generated thus:

# First Item
# Second Item
# Third Item
etc

1. First Item
2. Second Item
3. Third Item

Section headings are delimited by one or more occurrences of the equals symbol '='. The number of these symbols denotes the 'level' of that section. The highest level sections have one '=', whereas sub-sections and their child sub-sub-sections have 2 or more '=' symbols.

= Heading 1 =
Some text...

= Heading 2 =
== Heading 3 ==
Some more text etc...

Note that the KB Wiki article that is prepared for contributors typically has the major section items defined for you in accordance with a KB Wiki template.

Having entered the basic text you can save your changes by clicking on the 'Save page' button at the foot of the page. It is also possible to preview the page before saving the changes by means of the 'Show preview' button.

The user should use the Editing Tool icons bar at the top of the page to generate these and other WikiText elements more conveniently.

Links

Being a hypertext document, a KB Wiki page benefits greatly from the use of links both within the page from one section to another, to other pages in the same Wiki, and to external web sites. The notes in this section explain how to add these different kinds of link to a page.

Two basic types of link are possible:

• internal wiki links- eg, linking one wiki page to another wiki page, or
• a link to an external web site.

The first kind of link is based on the name of the Wiki Page title and takes the following general form consisting of two parts. The first part is a reference to the Wiki page title being linked to. The second part is the descriptive text that is displayed in the Wiki page as the hyperlink.

[[Link_page_title|Description of Link]]

Note that if the second part, ie, the description of the link, is omitted then the Link url is displayed verbatim instead.

For example, the link to the KB Wiki page can be defined as follows in your article:

[[Main_Page|Back to KB Wiki Home Page]]

It is important to note that if the page being linked to doesn't exist the Wiki invites you to create the page.

The following example shows how to jump to a particular named section in another page:

[[About-url#How_to_Contribute_Articles_and_Provide_Feedback|How to contribute articles etc]]

which is displayed thus:

How to contribute articles etc

That is, the section name should follow the name of the page with a hash '#' symbol. This part of the url denotes an 'anchor'. Note that all sections can be treated as anchors and that it is possible to introduce your own anchors into a page using span or div HTML elements. These are the exceptions to the general rule noted above.

So for example, the following definition is used to identify a link to a particular anchor in another page:

Transport Equation for Turbulent Dissipation

which is identified in that page as an anchor using the following WikiText:

<span id="disspn-eqn">
Dissipation Rate transport equation:
</span>

External links are defined in a similar fashion to internal links but with the difference that single delimiters are used and a space separates the URL from the description text.

[ {link url} {link name or description} ] 

For example, the link to Google would be defined as follows:

[http://www.google.com Search Google...]

which is rendered as the following link:

Search Google...

How to add images

Images in MediaWiki have similarities to the WikiText link elements described above. We describe here the process for adding an image to a Wiki page using these image links.

• Save the image you need to a file on your machine, giving it a memorable name- whatever you deem appropriate.
• In the editing page make sure your cursor is in the required location for your image then on the top where all the tool icons are, click on the icon that looks like a little picture frame, titled "embedded file".

This will generate an internal image link which looks like this in WikiText:

[[Image:Example.jpg]]

There are a number of ways in which you can upload the file. The first is to click on the image link that you have just created to take you to a File Upload page. Alternatively, use the left hand navigation bar and click on "Upload file" under the "Tool Box" folder to take you to the same page.

• Click on "Browse" to find the saved image on your own machine and then once located click on "Upload File".
• The desired image should come up with its precise location name. This is important because if you don't put the exact name of the uploaded picture into the image link, the picture will not be viewed in the wiki- instead a red link will come up showing that something is wrong with this image file. The name of the uploaded file will be shown in blue under the picture once you have clicked on the "Upload File" button.
• Go back into the page you are editing by clicking on the back bar, and type into the image link the name of your uploaded image eg: Image:wavevortex_1.gif; Image:wave_vortex_1.GIF; Image:Wave vortex1.gif etc.

The examples described here are to show you how to enter your image name. Make sure you leave in the prefix Image:. Note also that the uploaded image name is permitted to have underscores, upper-case letters, spaces, numbers etc. Be sure that when you add the image link to your page it must be exactly the same name as the uploaded image.

Click on save at the bottom of the editing page and the image should appear in the wiki. If all that is seen is a red link instead of a picture it is probably because there is an error in the name and so has not been recognised.

Tables

The documentation on the MediaWiki site provides more information on this particular subject (Tables Help); more detailed help is available here. The notes in this section are to show a simple example that can be used as a starting point for very simple tables.

The following defines a simple 3 column by 3 row table with a table caption and titles for each column. The border parameter specifies that a thin line is used for the border between the table cells.

{| border="1"
|+Name and Address Table
! Second Name
! First Name
! Address
|-
| Bloggs
| Joe
| 51 Stapleton Avenue, Brizzle
|-
| Smith
| Jeff
| 45 Belle View, Brizzle
|-
| Hughes
| Paul
| 54 London Road, Barth
|}

Name and Address Table

Second Name	First Name	Address
Bloggs	Joe	51 Stapleton Avenue, Brizzle
Smith	Jeff	45 Belle View, Brizzle
Hughes	Paul	54 London Road, Barth

Adding Equations

Equations are the most challenging but rewarding part of authoring technical content for the wiki. More information on adding equations can be found here.

Wiki Help Reference Sites

• An excellent set of help pages for editing MediaWiki based sites can be found at this link: Media Wiki Help Contents
• A useful 'cheat sheet' for MediaWiki commands can be found at the Wikipedia site: Cheatsheet