How to contribute: Difference between revisions

From KBwiki
Jump to navigation Jump to search
Line 13: Line 13:
* '''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!
* '''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.
* '''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.


* '''Resist using Style elements!''' Using individual style attributes on WikiText elements often makes the wiki text difficult to edit or read.  If they are used, then they are reserved for the QNET Wiki Editorial team only and should not be used within articles.  If you absolutely need them then contact us and we will seek alternatives where possible.
* '''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 QNET Wiki Editorial 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 reasosns so please don't attempt to add them.
* '''Don't attempt to use JavaScript, Flash or similar items''' These cannot be added to a page for security reasosns so please don't attempt to add them.

Revision as of 13:59, 2 July 2009

Contributing material to the QNET Knowledge Base

In this article, the basic procedures for authoring content for the QNET Wiki are described. These notes are intended for those QNET users who have previously submitted a request to contribute a QNET article (eg, for an AC or UFR). The procedure for requesting new content is not described here but is outlined elsewhere on this site []. Therefore, the basic assumption is that a new QNET 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 Wiki article.

General Advice

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

  • Keep it brief! Each AC or UFR 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.
  • 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 QNET Wiki Editorial 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 reasosns so please don't attempt to add them.

Basic Steps

Entering Edit mode

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

Wiki page.jpg

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

Wiki edit tab.jpg

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.

Wiki edit red.jpg

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 or the client machine has very low performance. An example of this links is given below:

Using the Edit Toolbar

Links

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


How to add images

It is possible to add images to your article pages based on WikiText link elements described earlier.

  • Save the image you need to a file on your machine, giving it a memorable name- whatever you deem appropiate.
  • 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 easiest 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.

  • 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 ie; File:Wavevortex 1.gif; File:Wave vortex 1.GIF; File:Wave vortex1.gif

The examples described here are to show you how to enter your image name. Make sure you leave in

Image:.

. Note 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 recongnised.

Adding Equations

References