Difference between revisions of "Wiki editing guidelines"
| Line 4: | Line 4: | ||
The main aim of these guidelines is to help keep information stored on the wiki usable, organised and discoverable. This means that other users will be able to get the best use of out you help. | The main aim of these guidelines is to help keep information stored on the wiki usable, organised and discoverable. This means that other users will be able to get the best use of out you help. | ||
| + | |||
| + | ==General Principles== | ||
| + | |||
==Page Formatting== | ==Page Formatting== | ||
| Line 17: | Line 20: | ||
Some times you will have a few tokens of code that you wish to use in a sentance. To do this use the <code> tag. For example when I want to talk about <code>$c->{set_eprint_automatic_fields}</code> in a sentance. | Some times you will have a few tokens of code that you wish to use in a sentance. To do this use the <code> tag. For example when I want to talk about <code>$c->{set_eprint_automatic_fields}</code> in a sentance. | ||
| + | |||
| + | ===Lists=== | ||
| + | Bulleted lists are a very clear and easy way to convey information clearly and concidely. Do not shy away from using bulleted lists or numbered lists (see the mediawiki article above). You can also easy nest lists. | ||
| + | |||
| + | |||
| + | == Writing Style == | ||
| + | |||
| + | Writing style is very important. When people come to use your wiki page they are trying to find the information they want quickly. Try not to over elaborate. Use short sentances and short paragraphs. | ||
| + | |||
| + | Most readers will be programmers an as a rule do much care if the grammer isnt perfect (though that helps). If you have something useful to add we would rather you wrote something with dodgey grammer than nothing at all. | ||
| + | |||
| + | If you use code snippets from your repository you may have to modify it slightly so that general readers can understand. You dont want to go into a lengthly explaination of your repository set up just so that you can quote code from it. | ||
Revision as of 11:27, 8 June 2010
This is a guide to best practices when editing the EPrints wiki.
The EPrints wiki uses a standard installation of MediaWiki. A basic guide to understanding wiki markup for formatting pages can be found here: http://www.mediawiki.org/wiki/Help:Formatting
The main aim of these guidelines is to help keep information stored on the wiki usable, organised and discoverable. This means that other users will be able to get the best use of out you help.
Contents
General Principles
Page Formatting
Headings
To make a page easy to navigate internally it is advisable to use sensibly nested headings and sub headings. This will result in neat table of contents at the top of your page. It also makes the document more readable.
If your page is very short you may want to remove the table of contents by placing the __NOTOC__ directive at the top of the page.
Code in text
Often you will want put code snippets in text. If you have a line of code of more place the code in a <pre> like so:
#My lines of code go in here
Some times you will have a few tokens of code that you wish to use in a sentance. To do this use the <code> tag. For example when I want to talk about $c->{set_eprint_automatic_fields} in a sentance.
Lists
Bulleted lists are a very clear and easy way to convey information clearly and concidely. Do not shy away from using bulleted lists or numbered lists (see the mediawiki article above). You can also easy nest lists.
Writing Style
Writing style is very important. When people come to use your wiki page they are trying to find the information they want quickly. Try not to over elaborate. Use short sentances and short paragraphs.
Most readers will be programmers an as a rule do much care if the grammer isnt perfect (though that helps). If you have something useful to add we would rather you wrote something with dodgey grammer than nothing at all.
If you use code snippets from your repository you may have to modify it slightly so that general readers can understand. You dont want to go into a lengthly explaination of your repository set up just so that you can quote code from it.
