|
|
||||
|
|
|
||||
| Page date Sat Feb 22 16:03:34 2014 . | Improve this page |
This document describes recommended approaches for the format and structure of wiki pages.
The guide is aimed to Wiki pages creators, editors and reviewers.
This guide assumes the existence of a standard MediaWiki instance and the wiki syntax is specific to MediWiki.
The wiki pages should be well structured, with multiple levels of headers.
= Level 1 Header =
== Level 2 Header ==
=== Level 3 Header ===
The recommended syntax is with one space between the equal signs and the content.
= Level 1 Header =
is preferred over
=Level 1 Header=
The headers are also used to generate the page hierarchical table of contents; all headers, down to the deepest level. This also dictates the limit between too few and too many headers: if the table of contents looks too long, with unnecessary details, then you probably went too far with adding headers, and some of the deepest levels should be removed. Similarly, if the page is long but the table of contents is just a few lines, you might consider adding some more intermediate headers.
Regardless of line legth, without any special characters, multiple text lines are concatenat and grouped in a single paragraph. To end a paragraph and open another one, use an empty line.
This is the
first paragraph.
And this is the second.
Text that should be more visible than the rest of the sentence, can be marked as bold or, when appropriate, italic.
Lists are a very convenient and nice looking way to present enumerations and should be used as often as needed.
The usual format is a bulleted list:
List
List
* item 1
* item 2
For ordered items, or when it is necessary to refer to a particular item, numbered lists are available:
Orderd
Orderd
# first
# second
Please note that unless ordered or referred items, bulleted lists are preferred over numbered lists.
It is not only perfectly possible to define, but also recommended to use multiple level lists:
Multilevel
Multilevel
* level 1
** level 2
*** level 3
This works for numbered lists too.
When the text requires, for example when quoting a sentence, indentation can be used.
This sentence quotes from the classics
: This sentence quotes from the classics
Multilevel lists and indentation can be mixed, if needed.
three three item one three def one
four
four def one
this looks like a continuation
and is often used
instead of <br />
# one
# two
#* two point one
#* two point two
# three
#; three item one
#: three def one
# four
#: four def one
#: this looks like a continuation
#: and is often used
#: instead<br />of <nowiki><br /></nowiki>
# five
## five sub 1
### five sub 1 sub 1
## five sub 2
Tables are not exactly the easiest feature of formats like wiki or html.
The syntax, although quite simple, is not easy to remember, so the best way to enter tables is with… copy/paste.
| First Column | Second Column |
|---|---|
| Bread | Pie |
| Butter | Ice cream |
{| class="wikitable"
! First Column !! Second Column
|-
| Bread || align="center" | Pie
|-
| Butter || Ice cream
|}
To ease navigation, it is recommended to link from one wiki page to another. If the displayed text needs to be different than the link, it can be specified.
[[/Main_Page|different text]]
Similarly, external links can be entered behind any text part:
[http://mediawiki.org MediaWiki]
Use: <pre> … </pre> for preformatted code, or <code> … </code> for pieces of source code that requires coloured syntax.
General punctuation rules should be respected, for example
The only exception to the rule are the open parenthesis, where the rule is symmetrical, i.e. one space before and no space after.
Capital letters should be used to mark:
Although a matter of personal preferences, the (ab)use of capital letters inside titles, headings, and sub-headings should be avoided.
One usually arguable topic is the punctuation to be used for lists.
There is no single rule to fit all needs.
Short enumerations look cleaner without any punctuation and without capital letters:
Sample list:
If the items of the list are in general short enumeration and only occasionally contain multiple sentences, except the first one, the general rules apply, i.e. the subsequent sentences start with capital letters and are finished with dot.
Sample list with some sentences:
If the list items are long, and might be considered parts of a long sentence that was split for readability reasons, itms should end with usual punctuation marks, like semi-colon, and the last item should end with a dot.
One possibility is:
If the list items are independent sentences, and you feel like they should start with capital letters and be ended with full stops, then you should probably reconsider the option of using lists and consider indentation.
According to the rule used for capital letters in titles, capital letters should be avoided in wiki pages names.
For example Main page is preferred to Main Page.
The border between major and minor is not that obvious, but the rule should be that when significant content is added, the edit should be major. If the edit consists only of typos, spaces, punctuation, it is minor.
For the rest, it depends. As another rule, we can consider major all changes that:
In practical terms, the difference between major and minor edits is used when displaying the Recent changes page, and allows a better overview on the edit activity.
It is recommended for all users to set their preferences so that by default all edits are minor, and to manually mark major edits.
