View source for Help:MediaWiki help policy

{{H:h|Moderator toc}}
This page discusses content atomization, internationalization, portability, and style issues pertaining to the [[Help:Contents|MediaWiki software help]].

The help namespace is reserved for the MediaWiki ''software'' Help.  Please avoid writing content that is specific only to Wikimedia in the MediaWiki help. If you have content about Wikimedia, go to the [[m:Main Page]] and find the correct page to build off.

The intention is that the master page of any help page in a given language is on Meta. The wikitext is copied without modification (hence very easily, either manually or automatically) into another wiki of the same language.  Differences in content are achieved by templates.

Help pages are not necessarily written by developers. If some behavior of the software, described on the help pages, strikes you as odd and/or inconvenient, do not assume that it is intentional or even that developers are aware of it. Please [[mediazilla:|file a bug report or feature request]] to bring it to their attention, and link to the bug report from the Help or Help talk page. See also [[m:MediaWiki feature request and bug report discussion|MediaWiki feature request and bug report discussion]].

Developers are encouraged to add technical details to help pages, based on their knowledge of the internal workings of the software, and/or to provide links to pages on the [http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/ subversion] server, etc.

Help pages are largely based on observed behavior of MediaWiki, including accidental features and side-effects. These may change with changes of implementation. See also [[w:en:Template_talk:Qif#Undefined_MediaWiki_behavior.3F|undefined MediaWiki behavior]].

{| align="right"
| {{shortcut|[[m:WM:HELP|WM:HELP]]}}
|}
== Internationalization ==

There is a separate help namespace for several languages on Meta:
{|
!ISO
!Language
!ns
|'''Help'''
!colspan="2"|Pages
|-
|en|| English || <tt>[{{fullurl:Special:Allpages|namespace=12}} &#160;12]</tt> || [[Help:Contents|{{NS:12}}]]
|align="right"| {{PAGESINNS:12}} || {{PAGESINNS:13}}
|-
|de|| German || <tt>[{{fullurl:Special:Allpages|namespace=100}} 100]</tt> || [[Hilfe:Handbuch|{{NS:100}}]]
|align="right"| {{PAGESINNS:100}} || {{PAGESINNS:101}}
|-
|fr|| French || <tt>[{{fullurl:Special:Allpages|namespace=102}} 102]</tt> || [[Aide:Aide|{{NS:102}}]]
|align="right"| {{PAGESINNS:102}} || {{PAGESINNS:103}}
|-
|da|| Danish || <tt>[{{fullurl:Special:Allpages|namespace=104}} 104]</tt> || [[Hjælp:Indhold|{{NS:104}}]]
|align="right"| {{PAGESINNS:104}} || {{PAGESINNS:105}}
|-
|eo|| Esperanto || <tt>[{{fullurl:Special:Allpages|namespace=106}} 106]</tt> || {{NS:106}}
|align="right"| {{PAGESINNS:106}} || {{PAGESINNS:107}}
|-
|sv|| Swedish || <tt>[{{fullurl:Special:Allpages|namespace=108}} 108]</tt> || {{NS:108}}
|align="right"| {{PAGESINNS:108}} || {{PAGESINNS:109}}
|-
|es|| Spanish || <tt>[{{fullurl:Special:Allpages|namespace=110}} 110]</tt> || [[Ayuda:Contenido|{{NS:110}}]]
|align="right"| {{PAGESINNS:110}} || {{PAGESINNS:111}}
|-
|it|| Italian || <tt>[{{fullurl:Special:Allpages|namespace=112}} 112]</tt> || [[Aiuto:Sommario|{{NS:112}}]]
|align="right"| {{PAGESINNS:112}} || {{PAGESINNS:113}}
|-
|ja|| Japanese || <tt>[{{fullurl:Special:Allpages|namespace=114}} 114]</tt> || {{NS:114}}
|align="right"| {{PAGESINNS:114}} || {{PAGESINNS:115}}
|-
|nl|| Dutch || <tt>[{{fullurl:Special:Allpages|namespace=116}} 116]</tt> || [[NL_Help:Inhoudsopgave|{{NS:116}}]]
|align="right"| {{PAGESINNS:116}} || {{PAGESINNS:117}}
|-
|pl|| Polish || <tt>[{{fullurl:Special:Allpages|namespace=118}} 118]</tt> || [[Pomoc:Spis_tre%C5%9Bci|{{NS:118}}]]
|align="right"| {{PAGESINNS:118}} || {{PAGESINNS:119}}
|-
|pt|| Portuguese || <tt>[{{fullurl:Special:Allpages|namespace=120}} 120]</tt> || {{NS:120}}
|align="right"| {{PAGESINNS:120}} || {{PAGESINNS:121}}
|-
|ca|| Catalan || <tt>[{{fullurl:Special:Allpages|namespace=122}} 122]</tt> || [[CA_Ajuda:Contingut|{{NS:122}}]]
|align="right"| {{PAGESINNS:122}} || {{PAGESINNS:123}}
|-
|no|| Norwegian || <tt>[{{fullurl:Special:Allpages|namespace=124}} 124]</tt> || [[Hjelp:Innhold|{{NS:124}}]]
|align="right"| {{PAGESINNS:124}} || {{PAGESINNS:125}}
|-
|zh|| Chinese || <tt>[{{fullurl:Special:Allpages|namespace=126}} 126]</tt> || [[%E5%B8%AE%E5%8A%A9:%E7%9B%AE%E5%BD%95|{{NS:126}}]]
|align="right"| {{PAGESINNS:126}} || {{PAGESINNS:127}}
|-
|ru|| Russian || <tt>[{{fullurl:Special:Allpages|namespace=128}} 128]</tt> || [[%D0%9F%D0%BE%D0%BC%D0%BE%D1%89%D1%8C:%D0%A1%D0%BE%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D0%BD%D0%B8%D0%B5|{{NS:128}}]]
|align="right"| {{PAGESINNS:128}} || {{PAGESINNS:129}}
|-
|??|| unknown || <tt>[{{fullurl:Special:Allpages|namespace=130}} 130]</tt> || {{NS:130}}
|align="right"| {{PAGESINNS:130}} || {{PAGESINNS:131}}
|-
|??|| unknown || <tt>[{{fullurl:Special:Allpages|namespace=132}} 132]</tt> || {{NS:132}}
|align="right"| {{PAGESINNS:132}} || {{PAGESINNS:133}}
|-
|??|| unknown || <tt>[{{fullurl:Special:Allpages|namespace=134}} 134]</tt> || {{NS:134}}
|align="right"| {{PAGESINNS:134}} || {{PAGESINNS:135}}
|-
|??|| unknown || <tt>[{{fullurl:Special:Allpages|namespace=136}} 136]</tt> || {{NS:136}}
|align="right"| {{PAGESINNS:136}} || {{PAGESINNS:137}}
|-
|??|| unknown || <tt>[{{fullurl:Special:Allpages|namespace=138}} 138]</tt> || {{NS:138}}
|align="right"| {{PAGESINNS:138}} || {{PAGESINNS:139}}
|}

{{H-langs:Contents}}

The [[Помощ:Съдържание|Bulgarian]], [[%CE%92%CE%BF%CE%AE%CE%B8%CE%B5%CE%B9%CE%B1:%CE%A0%CE%B5%CF%81%CE%B9%CE%B5%CF%87%CF%8C%CE%BC%CE%B5%CE%BD%CE%B1|Greek]], and [[Pomoč:Vsebina|Slovenian]] help pages are currently in the main namespace.

==Internal links==

To make the links to other help pages work, preferably the name of the help namespace on all projects in a given language is the same as that of the help namespace for that language on Meta.

For example, the help namespace on German projects is "Hilfe:"; this can be checked with links like [[w:de:help:a]], [[b:de:help:a]], etc.: "help" is automatically converted to the local name.

In e.g. Dutch projects the help namespace is called "Help", but on Meta the name is "NL_Help". In such a case a special provision is necessary to make links from one help page to another one in the same language work in all projects concerned. One method is to use links like <nowiki>[[{{SUBJECTSPACE}}:Naamruimte]]</nowiki>.

This can be put in templates, one can use [[Template:h:l]] for producing the link:
*<nowiki>{{h:l|a}}</nowiki> gives {{h:l|a}}.
*<nowiki>{{h:l|Contents}}</nowiki> gives {{h:l|Contents}}.
*<nowiki>{{h:l|MediaWiki help policy}}</nowiki> gives {{h:l|MediaWiki help policy}}.

*<nowiki>{{h:l|a|b}}</nowiki> gives {{h:l|a|b}}.
*<nowiki>{{h:l|Contents|b}}</nowiki> gives {{h:l|Contents|b}}.
*<nowiki>{{h:l|MediaWiki help policy|b}}</nowiki> gives {{h:l|MediaWiki help policy|b}}.

As demonstrated, existence detection and the self-link feature still work.

See also [[Help:Page for demos in the Help namespace#Portability of help pages to a namespace with a different name|Portability of help pages to a namespace with a different name]].

== Keeping project-specific material separate ==
For each subject/language combination the wikitext of the help page is the same on all projects. Differences in content are achieved by  templates.

Copies of the exact wikitext on other projects have the same tags; removing them from the imported help pages would not be practical, it would make updates cumbersome. However, a non-existing template shows up as an edit link to the non-existing template page. Therefore at least an empty template has to be created on the other projects. Alternatively it may have project-specific content.

A name conflict occurs when a template used on a help page is already in use on another project. Also, mixed use of capital and lower-case first letter gives problems on projects where the first letter, like other letters, is case-sensitive.

Therefore the names used for templates are restricted: the full template names start with "Template:h:" (on Meta and many other, but not all projects, the h is capitalized) and the tags use lower-case h. Each project should reserve these names for this purpose. 

In fact, the only tags are <nowiki>{{h:h|</nowiki>''parameter''}}, <nowiki>{{h:f</nowiki>|enname=''parameter'' }} (and the corresponding, deprecated <nowiki>{{h:f</nowiki>|langs=|enname=''parameter'' }}), <nowiki>{{h:|</nowiki>''parameter'' }}, <nowiki>{{h:l}}</nowiki>, and <nowiki>{{h:new|</nowiki>''parameter'' }}. The page [[Help:Template]] is an exception, it uses many demo templates. It is therefore not very suitable for copying to other projects. [[Help:Contents]] is also an exception, it is a composite page. 

All projects need to create templates with these four names, even if only to specify (by a blank template) that no content is desired.

Various constructions explained below use the fact that [[Help:Template#A_pair_of_double_or_triple_braces_inside_a_pair_of_double_braces|a template name and a parameter value can both depend on a parameter or variable]], in particular, in template calls, template names are expressed in terms of the variables <nowiki>{{SUBJECTSPACE}}</nowiki> and <nowiki>{{PAGENAME}}</nowiki>.

===Template:h:h===
<nowiki>{{h:h</nowiki><tt>|</tt>''parameter'' }} is at the top of every help page and refers to {{tim|h:h}}. On Meta it produces a box at the top, which is language dependent, defined by
<nowiki>{{h:h&#160;{{SUBJECTSPACE}}</nowiki><tt>|</tt>''parameter''&#160;}}, examples:
*{{tim|H:h Aiuto}}
*{{tim|H:h Help}}
*{{tim|H:h Hjelp}}
<small>'''Other languages''': {{H-langs:H:h Help}}</small>

The parameter taken by [[Template:H:h]] is passed to the language specific template where it's typically used to display a sidebar, e.g. ''parameter'' <tt>reader toc</tt> uses {{tim|Reader toc}} as sidebar for the English documentation. This template also adds the help page to [[:Category:Reader handbook]].

Depending on the help page and the browser long floating sidebars can overwrite the content, in that case it's better to specify '''no''' parameter.  [[Template:H:h|H:h]] then passes an empty string to e.g. [[Template:H:h Aide|H:h Aide]], where that could be handled as in {{tim|H:h Help}}. 
The handbook subcategory has then to be specified explicitly in the help page. If there are such subcategories, this organization is entirely optional.

===Template:h:f===
<nowiki>{{h:f</nowiki><tt>|</tt>enname=''pagename in English'' }} is at the bottom of every help page and refers to [[Template:h:f]]. On Meta it produces a box at the bottom, which is language dependent, defined by 
<nowiki>{{h:f&#160;{{SUBJECTSPACE}}</nowiki><tt>|</tt>enname=''pagename&#160;in&#160;English''&#160;}}, examples:
*[[Template:H:f Help]]
*[[Template:H:f Aide]]
*[[Template:H:f Hilfe]]
*[[Template:H:f Hjelp]]
<small>'''Other languages''': {{H-langs:H:f Help}}</small>

On Meta interlanguage links are provided in Template:H-langs:<nowiki>{{{</nowiki>enname}}}.

The above-mentioned template tag is the same for all translations of a help page, and can therefore conveniently be copied.

For further details and lists of translations see [[Help:Help page footer templates|Help page footer templates]]. Here's a [{{fullurl:m:Special:Whatlinkshere|target=Template:H:f}} list] of all existing pages using [[Template:h:f|h:f]] on Meta.

===Template:h:===
<nowiki>{{h:|</nowiki>''parameter'' }} can be put at arbitrary locations of help pages and refers to [[Template:h:]]. It is intended for short Meta-specific content (the parameter value). Other projects can select one of four meaningful definitions of the template with this name:
*leave it blank
*put a marker
*show the text like on Meta
*show the text like on Meta with a marker

==Use of the template tags by other projects==
*If h:l tags are used on a page for internal links within the namespace, then, for the page to work on another project, that project should of course have a copy of [[Template:h:l]].
*Content that should be the same on all help pages of a project can be put in the local templates h:h and h:f.
*Additional content in selected pages can be achieved with <nowiki>{{PAGENAME}}</nowiki>. Each help page can have its own template with additional content; e.g. on the English Wikipedia they are named Template:ph:<nowiki>{{PAGENAME}}</nowiki>, called inside h:f, and placed at the bottom of the page, above the links to the other help pages in the project. See e.g. [[w:Help:Variable]]. A disadvantage is that for all help pages without additional content an empty template has to be created. [[w:en:Template:h:f]] has no parameter, the two parameters in the call of h:f are ignored (surplus parameters are ignored, see [[Help:Template#Parameters]]).

==Categories==
Category tags should be written with the English word "Category"; that works on all projects, see [[Help:Namespace#Automatic_conversions_of_page_names|Automatic conversions of page names]]. Note however that there is only one Category namespace on Meta. You may want to avoid putting help pages of two languages together in a category on Meta, just because the word describing the category happens to be the same in the two languages.

== Naming ==

Use '''short names'''. [[Help:Editing]] is better than ''Help:How to edit a page'' Keep in mind that you may want to link to this page many times in the future, and choose a short, descriptive name. As a guideline, try to avoid titles longer than 20 characters, and use "-ing" instead of "How to...".

Most of your links will be piped links, of the form: <nowiki>[[help:editing|editing]]</nowiki>  a bug will be opened on the wikimedia bugzilla when a possible solution is found, as piped links are not quick to implement.  The feature request will be something like: "hide namespace when in that namespace" then the text will look normal.

==Portability ==
To ensure that a wiki that has these help pages imported into it does not have broken links:

The links from this namespace to other namespaces and other projects use [[help:interwiki linking|interwiki links]] or external link style.

Examples:
*[[help:template]] works, provided that that help page has been copied
*[[translation]] would point to that page on the same wiki, hence it would not work if there is no such page
*[[m:translation]]  would point to http://meta.wikimedia.org/wiki/translation, provided that interwiki links have been set up in the wiki, including m: to Meta-Wikipedia; it would work without that page being imported into the wiki.
*[[w:en:HTML]] points to http://en.wikipedia.org/wiki/HTML, provided that interwiki link w: has been set to point to a Wikipedia, as is the case for Wikimedia projects (w: points from a non-Wikipedia to the Wikipedia in the same language, and from a Wikipedia to the English Wikipedia); using the prefix w:en ensures that the link also works on non-English projects that use the English help pages.

=== Older MediaWiki versions ===

When updating a help page for major MediaWiki version change, you can create a [[subpage]] with the name of the older version, and move the old instructions into that subpage.

==  "Help talk:" namespace ==

The "Help talk:" pages are for:
*discussing the documentation
*discussing the software features concerned

===Discussing improvements in the software===

For discussing improvements in the software maybe use [[w:Village pump (technical)]], the page [[m:MediaWiki feature request and bug report discussion|MediaWiki feature request and bug report discussion]] is apparently a dead end.

For formal requests use [[mediazilla:]].

If the bug / feature request is being fixed or implemented, one can start creating the documentation for the feature in the help namespace, but be sure to specify what version the feature is targeted for, 

Moderators frown on discussion in content pages, so use the discussion page for any discussions to avoid problems. One can link to a bug on mediazilla by <nowiki>[[mediazilla:bugnumber]]</nowiki>.

==Templates ==
[[Template:ed]] is called within another template for easy editing of the other template from a page that calls this other template.
:<nowiki>{{ed|Template|this template}}</nowiki> gives {{ed|Template|this template}}
:<nowiki>{{ed|another template}}</nowiki> gives {{ed|another template}}
Where the naive I18N [[MediaWiki:Edit]] = {{MediaWiki:Edit}} isn't good enough [[Template:edi]] allows greater flexibility:
:<nowiki>{{edi|template name}}</nowiki> gives {{edi|template name}}
:<nowiki>{{edi|template name|link text}}</nowiki> gives {{edi|template name|link text}}

For other templates see [[Help:Help page footer templates]].

==See also==
*[[Meta:MetaProject to transfer content to MediaWiki.org|Proposal to transfer the English-language help pages]] to http://www.mediawiki.org
{{h:f|langs=|enname=MediaWiki help policy}}