Difference between revisions of "Wiki editing guidelines"
(Removed staff category) |
|||
(24 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
+ | [[Category:Howto]] | ||
This is a guide to best practices when editing the EPrints wiki. | 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 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 | + | 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. | |
− | |||
− | To add a plugin to the | + | Want a quick introduction? View the [[Training_Video:EPrints_Wiki_Basics|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 [[:Category:Howto|How-to]] or [[:Category:Plugins|Plugins]]. | ||
+ | |||
+ | To add a plugin to the How-to category add <nowiki>[[Category:Howto]]</nowiki>. 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. | 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 | + | Another way to increase discoverability of your ideas is good page formatting. |
==Page Formatting== | ==Page Formatting== | ||
Line 20: | Line 25: | ||
If your page is very short you may want to remove the table of contents by placing the <code> <nowiki>__NOTOC__</nowiki> </code> directive at the top of the page. | If your page is very short you may want to remove the table of contents by placing the <code> <nowiki>__NOTOC__</nowiki> </code> 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 | ||
+ | <pre>Applicable to 3.2.1+</pre> | ||
+ | If you know a page does not work for a version of EPrints (probably from experience) edit the page to include that. | ||
===Linking=== | ===Linking=== | ||
Line 25: | Line 35: | ||
===Code in text=== | ===Code in text=== | ||
− | Often you will want put code snippets in text. If you have | + | Often you will want put code snippets in text. If you have one line of code or more place the code in a <code><pre></code> like so: |
<pre> #My lines of code go in here </pre> | <pre> #My lines of code go in here </pre> | ||
− | Some times you will have a few tokens of code that you wish to use in a | + | The most readable way to present source code is to surround it with <code><source lang="...">source code here</source></code> tags, where <code>...</code> is the language name, such as perl or xml. For example: |
+ | |||
+ | <source lang="perl"> | ||
+ | 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; | ||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | 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 <code>$c->{set_eprint_automatic_fields}</code> in a sentence. | ||
===Lists=== | ===Lists=== | ||
− | Bulleted lists are a very clear and easy way to convey information clearly and | + | 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 | + | 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. |
Latest revision as of 22:22, 10 January 2022
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
Contents
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.