Difference between revisions of "Help:Wiki Community"

From Xen
m (Useful Built-in Wiki Pages)
(Wiki Conventions)
 
(44 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<!-- MoinMoin name:  XenDocsSquad -->
+
Before you continue reading, [[Special:UserLogin|join the wiki as a user]]. We do not require for you to do this, but encourage you to register.
<!-- Comment:        Added anchors -->
+
__TOC__
<!-- WikiMedia name: XenDocsSquad -->
 
<!-- Page revision:  00000010 -->
 
<!-- Original date:  Fri Oct 14 22:54:52 2011 (1318632892000000) -->
 
__NOTOC__
 
<!-- ## Please edit system and help pages ONLY in the moinmaster wiki! For more -->
 
<!-- ## information, please see [[MoinMaster]]:[[MoinPagesEditorGroup]]. -->
 
<!-- ##master-page:[[Category:Template]] -->
 
<!-- ##master-date:Unknown-Date -->
 
<!-- #format wiki -->
 
<!-- #language en -->
 
 
 
Before you continue reading, join the wiki as a user. We do not require for you to do this, but encourage you to register.
 
 
 
 
{| border="0" valign="top" cellpadding="2" cellspacing="0"
 
{| border="0" valign="top" cellpadding="2" cellspacing="0"
 
|
 
|
Line 21: Line 8:
 
* Recognize community members for their contributions
 
* Recognize community members for their contributions
 
* Make new Wiki much more manageable by using Categories and other proven Wiki tools
 
* Make new Wiki much more manageable by using Categories and other proven Wiki tools
 +
* Help migrate pages from the old Wiki: [[Wiki Community/Migration Instructions from Old to New Xen Wiki|Migration Instructions from Old to New Xen Wiki]]
 
|http://www.xen.org/images/blog/UncleSamSmall.png
 
|http://www.xen.org/images/blog/UncleSamSmall.png
 
|}
 
|}
  
 
= Wiki Conventions =
 
= 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.  
+
We want to make it as easy as possible for users to use and find content in the new Wiki and also ensure that the Wiki remains up-to-date.
 +
 
 +
== Templates ==
 +
The Xen wiki provides a number of templates. Templates are normally documented. You can find the most commonly used templates and their documentation at [[:Category:Templates|Category:Templates]].
  
 
== Useful Built-in Wiki Pages ==
 
== Useful Built-in Wiki Pages ==
Line 44: Line 35:
 
|                                               
 
|                                               
 
|[[Special:WantedCategories|Wanted Categories]] &raquo;&raquo; Create category
 
|[[Special:WantedCategories|Wanted Categories]] &raquo;&raquo; Create category
|[[:Category:Contains_TODO|TODO Item]] &raquo;&raquo; Contains TODO item
+
|[[:Category:Contains_Needs_Formatting|Needs formatting]] &raquo;&raquo; Easy fix for a beginner
 
|-
 
|-
 
|                                               
 
|                                               
 
|[[Special:WantedTemplates|Wanted Templates]] &raquo;&raquo; Create template
 
|[[Special:WantedTemplates|Wanted Templates]] &raquo;&raquo; Create template
 +
|[[:Category:Contains_TODO|TODO Item]] &raquo;&raquo; Contains TODO item
 
|}
 
|}
  
 +
{{Anchor|templates}}
 
== Managing Pages via Templates ==
 
== Managing Pages via Templates ==
 
{|style="vertical-align: top; border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
 
{|style="vertical-align: top; border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
Line 59: Line 52:
 
|[[:Template:Needs_Archive]]
 
|[[:Template:Needs_Archive]]
 
|Indicates that this page needs to be archived. Please specify a reason why.
 
|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]]
 
|[[:Template:Needs_Delete]]
 
|Indicates that this page needs to be deleted. Please specify a reason why.
 
|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]]
 
|[[:Template:Needs_Refactor]]
Line 85: Line 84:
 
|[[:Template:Info]]
 
|[[:Template:Info]]
 
|This is a generic info box, which highlights some information about this page.  
 
|This is a generic info box, which highlights some information about this page.  
 +
|-
 +
|[[:Template:InfoLeft]]
 +
|Same as '''Info''' only that not centered
 
|-
 
|-
 
|[[:Template:Warning]]
 
|[[:Template:Warning]]
Line 92: Line 94:
 
'''Also see:'''
 
'''Also see:'''
 
* [http://www.mediawiki.org/wiki/Help:Templates Help on Templates]
 
* [http://www.mediawiki.org/wiki/Help:Templates Help on Templates]
* Example: <pre>{{Info|This is an infobox with this text in the box}}</pre>
+
* Example on how to use any of the above templates: <pre>{{Info|This is an infobox with this text in the box}}</pre>
 +
* Another example: <pre>{{Needs_Archive|This page is out-of-date: this project completed in 2009.}}</pre>
  
== Improving Navigation through Categories ==
+
== Categories ==
=== Common Categories ===
+
{{Anchor|categories}}
{|style="vertical-align: top; border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
+
 
|colspan="2" style="background-color:#38A3C7;"| '''''Categories by audience'''''
+
We use categories to help manage Wiki pages:
|-
+
* Each Wiki page should be at least in one category
|style="width: 20%;background-color:#58D3F7;"|'''Category'''
+
* Our category pages are not normally just indexes, but have a hand-edited header, which highlight important information.
|style="width: 80%;background-color:#58D3F7;"|'''When to use'''
+
 
|-
+
== Creating new pages ==
|[[:Category:Users]]
+
* Please make sure that you choose '''ONE''' of the following categories on a new page
|This document is for users of Xen or any project hosted on Xen.org
+
** '''Technology''': Xen, XCP, XenARM, PVOPS
|-
+
** '''Audience''': Beginners, Users, Developers,Project, Community
|[[:Category:Beginners]]
+
** '''Documentation Type''': Manual, Overview, FAQ, HowTo, Tutorial, Example, Compatibility, Glossary, Index (pick what fits best)
|This document is primarily targetted at beginners. Note that this category should primarily be used together with [[:Category:Users]].
+
** '''Life span''': choose category Transient if the document is transient (e.g. describes an event)
|-
+
** '''External''': choose category RefToExternalArticle if the is a stub linking to an external article
|[[:Category:Developers]]
+
* For other categories, please check [[Categories for Authors]] for more detail
|This document is for developers of Xen or any project hosted on Xen.org
+
* If your article is important, please go to the most relevant category and add the article to the hand-maintained content
|-
+
* '''Help on categories''': [[mediawikiwiki:Help:Categories|Help:Categories]]
|[[:Category:Project]]
+
 
|This document is primarily a project document such as a roadmap, TODO lis, minutes, etc. for a project hosted on Xen.org
+
== Creating a new Category ==
|-
+
* Please do NOT just create an empty category
|[[:Category:Community]]
+
* Add content the top the category: examples are [[:Category:Host_Install]] and [[:Category:Arch_Linux]]
|This document is a community document that doesn't fit elsewhere. It is intended for general information of Xen and the community at large
+
* Please describe the new category in
|-
+
** [[Categories for Users]]
|colspan="2" style="background-color:#38A3C7;"| '''''Categories by lifetime'''''
+
** [[Categories for Authors]]
|-
+
 
|style="width: 20%;background-color:#58D3F7;"|'''Category'''
+
== Improving Accessibility of topics with Trails ==
|style="width: 80%;background-color:#58D3F7;"|'''When to use'''
+
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]].
|-
+
 
|[[:Category:Transient]]
+
{{Trailbox||Trails_Usage
|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.
+
|{{Trail|Usage of Trails|
|-
+
* [[Template:Trailbox#Usage|Trailbox Syntax]]
|[[:Category:Archived]]
+
* [[Template:Trail#Usage|Trail Syntax]]
|This document has been archived. ''TODO:We probably will need archive versions of some Categories''
+
* [[Template:Trail#Trailbox_Trail_Example|Using both templates together]]
|-
+
}}
|colspan="2" style="background-color:#38A3C7;"| '''''Categories by document type''''' (note that these should be used in conjunction with audience categories)
+
}}
|-
+
 
|style="width: 20%;background-color:#58D3F7;"|'''Category'''
+
{{Anchor|archive}}
|style="width: 80%;background-color:#58D3F7;"|'''When to use'''
+
 
|-
+
== Archiving Pages ==
|[[:Category:Overview]]
+
Pages are archived in the following way:
|This document contains an Overview document for a specific topic. Overviews are typically introductory and contain definitions, trade-offs, basic concepts, etc.
+
* Add [[[[:Category:Archived|Category:Archived]]]] to the page
|-
+
* Rename the page from '''<pagename>''' to '''Archived/<pagename>'''
|[[:Category:FAQ]]
+
** If you do not have the right to rename pages, add [[[[Template:Needs_Archive]]]] to the page
|This document contains one or several frequently asked questions including answers
+
* Ensure you do the same with all sub-pages and translations
|-
+
* Keep all categories as they are
|[[:Category:HowTo]]
+
* If you cannot rename the page, then mark it with '''<nowiki>{{Needs_Archive|Reason why}}</nowiki>''', such that a wiki adminstrator can rename the page
|This document contains a HowTo document, which usually is a short tutorial
+
 
|-
+
= Multi-language Help and Conventions =
|[[:Category:Tutorial]]
+
For more information, see [[Xen:Multi-language Conventions|Multi-language Conventions]]
|This document contains a step-by-step tutorial for a fairly complex use-case
+
{{Anchor|Talk}}
|-
+
 
|[[:Category:Compatibility]]
+
= Use of Discussions: Talk pages =
|This document contains a information about software - software, software - hardware and other compatibility.
+
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 [http://www.mediawiki.org/wiki/Help:Navigation#Page_tabs “discussion” tab] at the top of the page. Simply edit the page as normal to add your comment.
|-
+
 
|[[:Category:Index]]
+
We encourage the use of talk pages. However, it would be good if you followed these Guidelines
|This document is largely an index to other pages.
+
'''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.
 +
'''Conventions''':
 +
* Always use the {{tl|comment}} template using <code><nowiki>{{Comment|~~~~:}} your comment text</nowiki></code> for commenting. Using the template makes it easier to find and address any comments made on talk pages. If you do not use this notation, your comment may be lost if it is not addressed immediately. Note that <code><nowiki>~~~~</nowiki></code> will render to something like <code><nowiki>[[User:Example|Simon Brown]] 21:55, 3 September 1991 (UTC)</nowiki></code>
 +
* Start a new discussion with a <code><nowiki>==level 2 heading==</nowiki></code> at the bottom of the page (or use the “{{lcfirst:{{int:addsection}}}}” tab).
 +
* Indent replies with colons (<code>:</code>) at the beginning of the line.
  
=== Other Categories ===
 
'''These sections still need to be written.'''
 
  
 +
'''Also See''':
 +
* [[Help:Talk Pages|More on Talk Pages (examples, etc.)]]
  
 
[[Category:Index]]
 
[[Category:Index]]
 +
[[Category:Wiki Management]]
 
[[Category:Community]]
 
[[Category:Community]]
 +
{{Languages}}

Latest revision as of 09:52, 7 June 2013

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 migrate pages from the old Wiki: Migration Instructions from Old to New Xen Wiki
UncleSamSmall.png

Wiki Conventions

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

Templates

The Xen wiki provides a number of templates. Templates are normally documented. You can find the most commonly used templates and their documentation at Category:Templates.

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.}}

Categories

We use categories to help manage Wiki pages:

  • Each Wiki page should be at least in one category
  • Our category pages are not normally just indexes, but have a hand-edited header, which highlight important information.

Creating new pages

  • Please make sure that you choose ONE of the following categories on a new page
    • Technology: Xen, XCP, XenARM, PVOPS
    • Audience: Beginners, Users, Developers,Project, Community
    • Documentation Type: Manual, Overview, FAQ, HowTo, Tutorial, Example, Compatibility, Glossary, Index (pick what fits best)
    • Life span: choose category Transient if the document is transient (e.g. describes an event)
    • External: choose category RefToExternalArticle if the is a stub linking to an external article
  • For other categories, please check Categories for Authors for more detail
  • If your article is important, please go to the most relevant category and add the article to the hand-maintained content
  • Help on categories: Help:Categories

Creating a new Category

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

For more information, see Multi-language Conventions

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.

Conventions:

  • Always use the {{comment}} template using {{Comment|~~~~:}} your comment text for commenting. Using the template makes it easier to find and address any comments made on talk pages. If you do not use this notation, your comment may be lost if it is not addressed immediately. Note that ~~~~ will render to something like [[User:Example|Simon Brown]] 21:55, 3 September 1991 (UTC)
  • Start a new discussion with a ==level 2 heading== at the bottom of the page (or use the “+” tab).
  • Indent replies with colons (:) at the beginning of the line.


Also See:

Languages Language: English