Wiki editing guidelines

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 your help.

Don't worry too much about editing the wiki. If you think something is wrong change it. We can always use the undo button. Without your edits we would not be able to keep the wiki up to date.

Want a quick introduction? View the Eprints wiki basics training video

Discoverability

There are a few things you can do to make your page discoverable. The most important of these is using Categories. You can see a full list of categories here: Special:Categories. Decide which category your page best fits into. Most user created pages will probably fit into How-to or Plugins.

To add a plugin to the How-to category add [[Category:Howto]]. You will find your page is immediately added to the index page for that category.

If you are not sure which category your page belongs in pick one which sounds sensible. It is better to have your page in the wrong category than in no category at all.

Another way to increase discoverability of your ideas is good page formatting.

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.

Versioning

When you write a wiki page it is very useful if you can include at the top the versions of Eprints you think this applies to. For example

Applicable to 3.2.1+

If you know a page does not work for a version of EPrints (probably from experience) edit the page to include that.

Linking

If you refer to material from another wiki page or another website please place a link to it. It makes moving around the wiki much smoother and really increases the usefulness of your document. Note: it will often be useful to link to a page in the EPrints_3_Reference category since this explains some of the configuration in detail.

Code in text

Often you will want put code snippets in text. If you have one line of code or more place the code in a <pre> like so:

 #My lines of code go in here 

The most readable way to present source code is to surround it with <source lang="...">source code here</source> tags, where ... is the language name, such as perl or xml. For example:

               my $fields = $session->get_conf('etd_ms','fields');					
               foreach my $field_conf (@{$fields})
		{
		   my $tags = $plugin->generate_tag($eprint, $field_conf);			
		   foreach my $tag (@{$tags})
		   {
					push @dcdata, ($tag) if $tag; 
		   }
		}

Some times you will have a few tokens of code that you wish to use in a sentence. To do this use the <code> tag. For example when I want to talk about $c->{set_eprint_automatic_fields} in a sentence.

Lists

Bulleted lists are a very clear and easy way to convey information clearly and concisely. 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 quickly find information. Try not to over elaborate. Use short sentences and short paragraphs.

Most readers will be programmers who, as a rule, don't much care if the grammar isn't perfect (though that helps). If you have something useful to add we would rather you wrote something with inaccurate grammar 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 don't want to go into a lengthy explanation of your repository set up just so that you can quote code from it.

If you find your page is getting very long you may find you should be making it into 2 pages. If you can logically split the information into two pages please do. It makes your document less daunting.