Difference between revisions of "Help:Wiki Community"

From Xen
Line 248: Line 248:
[[Category:Wiki Management]]
[[Category:Wiki Management]]

Revision as of 17:09, 30 November 2011

Before you continue reading, join the wiki as a user. We do not require for you to do this, but encourage you to register.

Why we need YOU!

The Xen.org Wiki has existed for some time and as with many Wiki's contains a lot of content that is out-of-date, or not relevant any more. We decided to migrate to a new MediaWiki based wiki, which allows us a fresh start. We hope to be able to mobilize Xen community members and are planning a number of regular activities and approaches:

  • Regular Document Days on IRC
  • Recognize community members for their contributions
  • Make new Wiki much more manageable by using Categories and other proven Wiki tools
  • Help magrate pages from the old Wiki: Migration Instructions from Old to New Xen Wiki

Wiki Conventions

We want to make it as wasy as possible for users to use and find content in the new Wiki and also ensure that the Wiki remains up-to-ate.

Useful Built-in Wiki Pages

These pages will help editors spot pages that need work.

Changes Missing Content Manage Pages
Recent Changes Wanted Pages »» Create page Uncategorized Pages »» Categorize
Related Changes Wanted Files »» Upload file Action Needed »» Needs deletion, refactor, review, ...
Wanted Categories »» Create category Needs formatting »» Easy fix for a beginner
Wanted Templates »» Create template TODO Item »» Contains TODO item

Managing Pages via Templates

Templates to help manage content
Template When to use
Template:Needs_Archive Indicates that this page needs to be archived. Please specify a reason why.
Template:Needs_Additions Indicates that this page is incomplete and can benefit from additions and improvements. Please specify what should be added.
Template:Needs_Delete Indicates that this page needs to be deleted. Please specify a reason why.
Template:Needs_Formatting Indicates that this page has some formatting issues. Please detail the issue.
Template:Needs_Refactor Indicates that this page needs to be refactored, such as merging or splitting. Please be concrete about the reason and proposed ocurse of action.
Template:Needs_Review Indicates that this page needs to be reviewed. If specific parts of the page need reviewing or are incorrect, please state in the macro.
Template:Needs_Rewrite Indicates that this page needs to be rewritten; in other words it is useful but contains lots of errors. Please provide more information in the macro.
Template:Needs_Recategorize Indicates that this page needs to be properly categorized. Please specify a reason why.
Template:TODO This is a generic template that indicates that something needs to be done to this page. Should only be used if the more specific templates are not applicable.
Other more generic templates
Template When to use
Template:Info This is a generic info box, which highlights some information about this page.
Template:InfoLeft Same as Info only that not centered
Template:Warning This is a generic warning box, which highlights some information about this page that typically warns the user of something.

Also see:

  • Help on Templates
  • Example on how to use any of the above templates:
    {{Info|This is an infobox with this text in the box}}
  • Another example:
    {{Needs_Archive|This page is out-of-date: this project completed in 2009.}}

Improving Navigation through Categories

Common Categories

Categories by audience
Category When to use
Category:Users This document is for users of Xen or any project hosted on Xen.org
Category:Beginners This document is primarily targetted at beginners. Note that this category should primarily be used together with Category:Users.
Category:Developers This document is for developers of Xen or any project hosted on Xen.org
Category:Project This document is primarily a project document such as a roadmap, TODO lis, minutes, etc. for a project hosted on Xen.org
Category:Community This document is a community document that doesn't fit elsewhere. It is intended for general information of Xen and the community at large
Categories by lifetime
Category When to use
Category:Transient This document has a limited lifespan (e.g. it describes an event or a short-lived activity). Pages in this category should be reviewed at least annually and archived appropriately.
Category:Archived This document has been archived.
Categories by document type (note that these should be used in conjunction with audience categories)
Category When to use
Category:Overview This document contains an Overview document for a specific topic. Overviews are typically introductory and contain definitions, trade-offs, basic concepts, etc.
Category:FAQ This document contains one or several frequently asked questions including answers
Category:HowTo This document contains a HowTo document, which usually is a short tutorial
Category:Tutorial This document contains a step-by-step tutorial for a fairly complex use-case
Category:Example This document primarily contains example configuration files, settings, scripts, etc.
Category:Compatibility This document contains a information about software - software, software - hardware and other compatibility.
Category:Index This document is largely an index to other pages.
Category:Glossary This document is a definition of a term used in the Xen community or more generally.
Categories by project or technology
Category When to use
Category:Xen This document is related to the Xen Hypervisor project or technology. This category may be used for user, developer as well as project categories.
Category:XCP This document is related to the XCP project or technology. This category may be used for user, developer as well as project categories.
Category:PVOPS This document is related to the PVOPS project or technology, which is about upstreaming and maintining Xen support in Linux. This category may be used for user, developer as well as project categories.
Category:XenARM This document is related to the XenARM project or technology. This category may be used for user, developer as well as project categories.

Other Categories

These are more specialised categories. Please ensure that these are used in conjunction with

Project type: Categories that relate to a specific project
Category When to use
Category:OCaml This document is related to the OCaml language, in which most of XCP is implemented.
Document type: Categories that are mainly relevant to developers
Category When to use
Category:Development Process This document describes a process or technique relates to projects on Xen.org. Documents in this category are mainly relevant for developers.
Category:Design Document This category contains design documents, architecture descriptions, and so on: in short it contains documents that describe how parts of the codebase work. Documents in this category are mainly relevant for developers.
Document type: Categories that are mainly relevant to users
Category When to use
Category:Release Notes This document describes Release Notes for a specifc project or product hosted on Xen.org.

Improving Accessibility of topics with Trails

Trails are sequences of documents (or indeed sections of documents) that are suggested to be read in a certain order. Note that trails are automatically added to the Category:Trail.

Usage of Trails

Archiving Pages

Pages are archived in the following way:

  • Add [[Category:Archived]] to the page
  • Rename the page from <pagename> to Archived/<pagename>
  • Ensure you do the same with all sub-pages and translations
  • Keep all categories as they are
  • If you cannot rename the page, then mark it with {{Needs_Archive|Reason why}}, such that a wiki adminstrator can rename the page

Multi-language Help and Conventions

Icon Info.png Also see Category:Languages!

The Languages Template

Pages and categories which exist in multiple translations must have the {{Languages}} template at the bottom of the page. This allows user to see the translations that are available for that page.

If you use multiple languages, the {{Languages}} template must be on every page in that language.

The English page contains:

<!-- The content of the actual page is here. -->
<!-- The {{Languages}} template must be at the bottom of the page! -->
<!-- There should be NO empty lines after {{Languages}}  -->

The translated page contains:

<!-- The content of the actual page is here. -->
<!-- The {{Languages}} template must be at the bottom of the page! -->
<!-- There should be NO empty lines after {{Languages}}  -->
{{Languages|<name of English page>|<language code>}}

For example [[Main Page/pt]] contains

{{Languages|Main Page|pt}}

The English version of a page is always the main version of a page, with all other languages as sub-pages, named using the appropriate language code (see below).

Naming conventions for translated pages

Translated pages need to follow the following naming conventions.

<My Page Name>/<2 Letter Language Code>

The two letter language code must be one of the codes shown in the supported languages table, for example

Page Name Language
Main Page English
Main Page/de German
Main Page/es Spanish
Main Page/fr French
Main Page/ja Japanese
Main Page/ko Korean
Main Page/pt Portuguese
Main Page/pt-br Brazilian Portuguese
Main Page/zh Chinese


Examples of valid page names are:

[[Archived/XCI Getting Started/pt]]

Languages Category

Translated pages must be Categorized: they must contain a category of the form

[[Category:Languages/<Language code>]]

such that it is possible to find all pages of a specific language.


Examples of valid category names are:


Links for translated pages

You have to be careful when linking to other pages. Say you want to link to


If you use the page above, you will go to the English page. If you want to go to a translated page, the link must look as follows

[[DomU_Install_with_Virt-Manager/<language code>]]



If you keep links to English documents in a translation, it is a good idea to use the following convention

[[DomU_Install_with_Virt-Manager]] (English)

such that people see, that the document is in English.

Examples & Testing

Example Page

Note that it is important to follow the conventions as outlined here. If not followed, the language templates do not work properly and users will find it hard to find translated content.

Page Foo must contain


Page Foo/es must contain


The following notation also works, but is harder to use


Example Category

Page Category:Foo must contain


Page Category:Foo/es must contain


Testing whether you have done OK

You should be able to see the following:

  • A box called 'Languages on the English and translated page (see bottom of Main Page as an example)
  • A box called 'Languages on the English and translated category
  • The 'Languages box should show: English, The Language You added, languages somebody else added. If it doesn't, you probably used the wrong language macro on the English page.
  • Translated pages should be in the Language/<your language> category, e.g. Language/es. You should go to the category for your language and check whether all pages are in this category.

Language Policy


This page describes the current multi-lingual policy on wiki.xen.org.

The main page

The English version of our front page is located at Main Page. Translated versions are located at MediaWiki/code, where code is the language code (e.g. Main Page/fr).

Importantly, the rules about language codes (see below) should be followed here as well.

Other namespaces

Apart from the Main Page, no policy has yet been decided about other namespaces. For the time being, if you would like to create translations for pages in other namespaces then please do so as described for the Help: namespace, however content may be moved or deleted depending on the policy that is eventually adopted.

Note that the rule that English content should not be placed in sub-pages does not apply to other namespaces. This is one of the issues that needs resolving.

Language codes

Throughout wiki.xen.org you should use the language codes specified by the MediaWiki software when creating language-specific content (see Names.php for the full and up-to-date list).

Please also bear the following in mind:

  • If the language code is not found in Names.php then we should not host pages in that language.
  • If MediaWiki uses the 'incorrect' code for a language then you should also (for consistency) use that incorrect code here. If you think a code is incorrect you should discuss it on MediaWiki Bugzilla, and if this results in it being changed we will move the pages to match.
  • Note that some language codes in Names.php are now deprecated (e.g. zh-yue has been replaced with yue). In these cases only the most recent code should be used.
Languages Language: English

Use of Discussions: Talk pages

Every wiki page has an associated talk page which can be used for discussion and communicating with other users. Talk pages can be accessed by clicking the “discussion” tab at the top of the page. Simply edit the page as normal to add your comment.

We encourage the use of talk pages. However, it would be good if you followed these Guidelines What to discuss:

  • Keep focused on the task of building a wiki article: remember that editing the article itself is often a more effective means of communicating.
  • Use discussion pages only to support this process: the topic of conversation should generally revolve around what needs to be done to make the associated article better.
  • Talk pages are good in particular, if you suspect something is wrong with the content, but you do not quite know how to fix the page.


  • Start a new discussion with a ==level 2 heading== at the bottom of the page (or use the “+” tab)
  • Always sign your name after your comments. Use the four tildes “~~~~” wiki syntax (or the signature button signature button in the toolbar above the editing textbox). For more information see Help:Signatures.
  • Indent replies with colons (:) at the beginning of the line.

Also See:

Languages Language: English