Help:MediaWiki help policy

{{process header
 | title    = MediaWiki help policy
 | section  =
 | previous = ←[[WM:IAS|Information and statistics]]
 | next     =
 | shortcut = [[m:WM:HELP|WM:HELP]]
 | notes    = This page discusses content atomization, internationalization, portability, and style issues pertaining to the [[Help:Contents|MediaWiki software help]].
}}
{{H:h|Moderator toc}}

This is the Master Help repository for the MediaWiki Software. This is a help reference, not an encyclopedic article. It can contain help about using features in all ways, even in ways that violate specific site conventions or styleguides. Please do not go into excessive detail about a specific site's policy, although feel free to refer to it. Lastly, this page lists a few templates to aid in organizing this content.

== Master page on Meta; duplication requirement ==

For English-language wikis participating in this system, the master page of any help page is on Meta. (Note that the English Wikipedia no longer participates, see [[w:Wikipedia:Miscellany_for_deletion/Meta-based_Help:_content_templates]].) 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.

While some Meta pages are transferred to [[mw:]], see [[Meta:MetaProject to transfer content to MediaWiki.org]], for pages in the Help namespace (largely these are the pages in [[Help:Contents]] and [[:Category:English documentation]]) there are complications: on mediawiki.org the Help namespace is for public domain pages, and the help page system is multilingual. See also [[Meta talk:MetaProject to transfer content to MediaWiki.org]].

== Content guidelines ==
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.

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

== Internationalization ==
There is a separate help namespace for several languages on Meta:
{| class="prettytable plainlinks" style="text-align: center;"
!ISO !! Language !! number !! Help
|-
|en|| English || <tt>[{{fullurl:Special:Allpages|namespace=12}} &#160;12]</tt> || [[Help:Contents|{{NS:12}}]]
|-
|de|| German || <tt>[{{fullurl:Special:Allpages|namespace=100}} 100]</tt> || [[Hilfe:Handbuch|{{NS:100}}]]
|-
|fr|| French || <tt>[{{fullurl:Special:Allpages|namespace=102}} 102]</tt> || [[Aide:Aide|{{NS:102}}]]
|-
|da|| Danish || <tt>[{{fullurl:Special:Allpages|namespace=104}} 104]</tt> || [[Hjælp:Indhold|{{NS:104}}]]
|-
|eo|| Esperanto || <tt>[{{fullurl:Special:Allpages|namespace=106}} 106]</tt> || {{NS:106}}
|-
|sv|| Swedish || <tt>[{{fullurl:Special:Allpages|namespace=108}} 108]</tt> || {{NS:108}}
|-
|es|| Spanish || <tt>[{{fullurl:Special:Allpages|namespace=110}} 110]</tt> || [[Ayuda:Contenido|{{NS:110}}]]
|-
|it|| Italian || <tt>[{{fullurl:Special:Allpages|namespace=112}} 112]</tt> || [[Aiuto:Sommario|{{NS:112}}]]
|-
|ja|| Japanese || <tt>[{{fullurl:Special:Allpages|namespace=114}} 114]</tt> || [[ヘルプ:目次|{{NS:114}}]]
|-
|nl|| Dutch || <tt>[{{fullurl:Special:Allpages|namespace=116}} 116]</tt> || [[NL_Help:Inhoudsopgave|{{NS:116}}]]
|-
|pl|| Polish || <tt>[{{fullurl:Special:Allpages|namespace=118}} 118]</tt> || [[Pomoc:Spis_tre%C5%9Bci|{{NS:118}}]]
|-
|pt|| Portuguese || <tt>[{{fullurl:Special:Allpages|namespace=120}} 120]</tt> || [[Ajuda:Página principal|{{NS:120}}]] || 
|-
|ca|| Catalan || <tt>[{{fullurl:Special:Allpages|namespace=122}} 122]</tt> || [[CA_Ajuda:Contingut|{{NS:122}}]]
|-
|no|| Norwegian || <tt>[{{fullurl:Special:Allpages|namespace=124}} 124]</tt> || [[Hjelp:Innhold|{{NS:124}}]]
|-
|zh|| Chinese || <tt>[{{fullurl:Special:Allpages|namespace=126}} 126]</tt> || [[%E5%B8%AE%E5%8A%A9:%E7%9B%AE%E5%BD%95|{{NS:126}}]]
|-
|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}}]]
|-
|sl|| Slovenian || <tt>[{{fullurl:Special:Allpages|namespace=130}} 130]</tt> || [[Pomoč:Vsebina|{{NS:130}}]]
|-
|ar|| Arabic(العربية) || <tt>[{{fullurl:Special:Allpages|namespace=132}} 132]</tt> || {{NS:132}}
|}

{{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 within non-English namespaces==

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

== Templates ==
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 {{links-small|template|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:
*{{links-small|template|H:h Aiuto}}
*{{links-small|template|H:h Help}}
*{{links-small|template|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 {{links-small|template|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 {{links-small|template|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 were 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. A disadvantage was that for all help pages without additional content an empty template had to be created. [[w:en:Template:h:f]] had no parameter, the two parameters in the call of h:f were 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.

==Links from the English Help namespace==

To ensure that a wiki that has these help pages imported into it does not have broken links, the following templates need to be copied:
*{{links-small|template|H:ml}}
*{{links-small|w|template|H:mlm}}
*{{links-small|template|H:mlw}} (replace "w:" with "w:en:" on non-English projects).

Using these we can have the following links:

Link to another help page:
*Use internal link style, e.g. [[Help:Section]]; on another wiki this links to the local copy of that help page.

Link to a section of a help page:
*<nowiki>{{</nowiki>h:ml|Help:Administration|Protection|Protecting pages}} gives {{h:ml|Help:Administration|Protection|Protecting pages}}; on Meta, due to {{links-small|template|H:ml}}, it produces, e.g. on {{h:mlm|Help:Editing}}, a link in internal link style and also a "hidden external link", to allow a backlink [http://meta.wikimedia.org/w/index.php?title=Special%3ALinksearch&target=meta.wikimedia.org%2Fwiki%2FHelp:Administration%23Protection], which, unlike [[Special:Whatlinkshere/Help:Administration]], is specific for the target section; on another wiki with a copy of the template, e.g. {{links-small|w|template|H:ml}}, the copy of the source page, in this case {{h:mlw|Help:Editing}}, has a link to the  corresponding section of the corresponding local help page, in this case {{h:mlw|Help:Administration|Protection}} (on that wiki it is a link in internal link style). The backlinks are produced by  [http://en.wikipedia.org/w/index.php?title=Special%3ALinksearch&target=en.wikipedia.org%2Fwiki%2FHelp:Administration%23Protection].

Link to a page, or section of a page, in another namespace on Meta:
*<nowiki>{{</nowiki>h:mlm|translation}} gives {{h:mlm|translation}}; on Meta this is due to {{links-small|template|H:mlm}}, which redirects to {{links-small|template|H:ml}}; it produces an internal link and also a "hidden external link", to allow a backlink [http://meta.wikimedia.org/w/index.php?title=Special%3ALinksearch&target=meta.wikimedia.org%2Fwiki%2FTranslation]; on other wikis a copy of {{links-small|w|template|H:mlm}} is used, an adapted version of the template; this produces an interwiki link to the same page on Meta, provided that interwiki link m: to Meta has been set up in the wiki.

Link to a page, or section of a page, on the English Wikipedia:
*<nowiki>{{</nowiki>h:mlw|HTML element|Links and anchors|HTML element "a"}} gives {{h:mlw|HTML element|Links and anchors|HTML element "a"}}; on Meta, due to {{links-small|template|H:mlw}}, it produces a link in interwiki link style and also a "hidden external link", to allow a backlink [http://meta.wikimedia.org/w/index.php?title=Special:Linksearch&target=en.wikipedia.org/wiki/HTML_element%23Links]; on the English Wikipedia the corresponding template, {{links-small|w|template|h:mlw}}, redirected to Template:H:ml and produced a link in internal link style to the same page with backlink [http://en.wikipedia.org/w/index.php?title=Special:Linksearch&target=en.wikipedia.org/wiki/HTML_element%23Links]; on other wikis, with a copy of {{h:mlm|Template:H:mlw}} on Meta, a link in interwiki link style is produced, provided that interwiki link w: has been set to point to the English Wikipedia, as is the case for English-language Wikimedia projects (replace "w:" with "w:en:" on non-English projects).

Alternatively, for links to other help pages a separate version of h:ml could be used, containing the namespace name "Help". The prefix "Help:" would not be needed in the first parameter. Also, this template use would be useful if at some stage the help pages would be  [[Meta:MetaProject to transfer content to MediaWiki.org|moved to MediaWiki.org]], into a namespace different from Help (because that is used for public domain pages). For that purpose also ordinary internal links (not to a section) could be created with a call to the template. 

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