Help:MediaWiki help policy

This page is kept for historical interest. Any policies mentioned may be obsolete. If you want to revive the topic, you can use the talk page or start a discussion on the community forum.

Shortcut:
WM:HELP

This page discusses content atomization, internationalization, portability, and style issues pertaining to the MediaWiki software help.

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

Help pages on Meta were originally intended to be copied without modification (hence very easily, either manually or automatically) into another wiki of the same language. Diqfferences in content were thus achieved by templates. This system has been defunct for many years.

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 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 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 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 undefined MediaWiki behavior.

Internationalization

Help pages uses subpages to store translated versions.

For making translations, Translate extension is used.

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 {{h:h|parameter}}, {{h:f|enname=parameter }} (and the corresponding, deprecated {{h:f|langs=|enname=parameter }}), {{h:|parameter }}, {{h:l}}, and {{h:new|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 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 {{SUBJECTSPACE}} and {{PAGENAME}}.

Template:h:h

{{h:h|parameter }} is at the top of every help page and refers to Template:h:h [ talk edit history links ]. On Meta it produces a box at the top, which is language dependent, defined by {{h:h {{SUBJECTSPACE}}|parameter }}, examples:

Template:H:h Aiuto [ talk edit history links ]
Template:H:h Help [ talk edit history links ]
Template:H:h Hjelp [ talk edit history links ]

<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 reader toc uses Template:Reader toc [ talk edit history links ] 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. H:h then passes an empty string to e.g. H:h Aide, where that could be handled as in Template:H:h Help [ talk edit history links ]. 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

{{h:f|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 {{h:f {{SUBJECTSPACE}}|enname=pagename in English }}, examples:

Other languages: Template:H-langs:H:f Help

On Meta interlanguage links are provided in Template:H-langs:{{{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 page footer templates. Here's a list of all existing pages using h:f on Meta.

Template:h:

{{h:|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 {{PAGENAME}}. Each help page can have its own template with additional content; e.g. on the English Wikipedia they were named Template:ph:{{PAGENAME}}, called inside h:f, and placed at the bottom of the page, above the links to the other help pages in the project. 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).

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: [[help:editing|editing]] 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:

Template:H:ml [ talk edit history links ]
Template:H:mlm for use on other wikis [ talk edit history links ], to be copied to the local page Template:H:mlm
Template:H:mlw [ talk edit history links ] (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:

{{h:ml|Help:Administration|Protection|Protecting pages}} gives Protecting pages; on Meta, due to Template:H:ml [ talk edit history links ], it produces, e.g. on Help:Editing//meta.wikimedia.org/wiki/Help:Editing, a link in internal link style and also a "hidden external link", to allow a backlink [1], which, unlike Special:Whatlinkshere/Help:Administration, is specific for the target section; on another wiki with a copy of the template, e.g. w:Template:H:ml [ talk edit history links ], the copy of the source page, in this case [2], has a link to the corresponding section of the corresponding local help page, in this case Help:Administration#Protection (on that wiki it is a link in internal link style). The backlinks are produced by [3].

Link to a page, or section of a page, in another namespace on Meta:

{{h:mlm|translation}} gives Translation//meta.wikimedia.org/wiki/Translation; on Meta this is due to Template:H:mlm [ talk edit history links ], which redirects to Template:H:ml [ talk edit history links ]; it produces an internal link and also a "hidden external link", to allow a backlink [4]; on other wikis a copy of Template:H:mlm for use on other wikis [ talk edit history links ] with the name 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:

{{h:mlw|HTML element|Links and anchors|HTML element "a"}} gives HTML element "a"; on Meta, due to Template:H:mlw [ talk edit history links ], it produces a link in interwiki link style and also a "hidden external link", to allow a backlink [5]; on the English Wikipedia the corresponding template, w:Template:h:mlw [ talk edit history links ], redirected to Template:H:ml and produced a link in internal link style to the same page with backlink [6]; on other wikis, with a copy of 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 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 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 [[mediazilla:bugnumber]].

Templates

Template:ed is called within another template for easy editing of the other template from a page that calls this other template.

{{ed|Template|this template}} gives Edit this template

{{ed|another template}} gives Edit another template

Where the naive I18N MediaWiki:Edit = Edit isn't good enough Template:edi allows greater flexibility:

{{edi|template name}} gives +/-

{{edi|template name|link text}} gives link text

For other templates see Help:Help page footer templates.

Help:MediaWiki help policy

Master page on Meta; duplication requirement

Content guidelines

Internationalization

Templates

Template:h:h

Template:h:f

Template:h:

Use of the template tags by other projects

Categories

Naming

Links from the English Help namespace

Older MediaWiki versions

"Help talk:" namespace

Discussing improvements in the software

Templates

See also

Links to other help pages