Wikipedia:Template documentation

Templates are a very powerful feature of MediaWiki, but can be confusing to new users and even experienced users can have difficulty making sense of the more complex ones. Templates should therefore be accompanied by documentation to improve usability.

Template documentation should explain what a template does and how to use it. It should be simple enough that a user without complete knowledge of the intricacies of template syntax—which includes many experienced contributors who focus their attention elsewhere—can use it correctly. This is especially true in the case of very widely used templates.

Editors should defer to official policies or guidelines when template documentation pages are inconsistent with established community standards and principles. Editors should also avoid "quoting" template documentation pages as though they are policy—including this how-to guide. Template documentation pages can be written without much—if any—debate, as opposed to Wikipedia policies that have been thoroughly vetted by the community (see WP:Local consensus for details).

What to include[]

Template documentation should cover:

The English Wikipedia is a source of templates for hundreds of other Wikipedias and sister projects. Often, templates are fully self-contained, so the process easy: the contents are simply copied to a new template page at the other wiki, and everything works. However, on more complex templates, the template may invoke a module, transclude other templates, only work if paired with a separate template, or need particular CSS or Javascript code to work. In these cases, it is helpful to include a brief list of templates or other code that this one requires, at the end of the documentation.

Where to place it[]

A template's page in the Template namespace is the location for the template code that controls the look and behavior of that template. What usually appears underneath the title on the rendered Template: page (as opposed to the window on the Edit tab or, in the case of templates whose code is protected, the View source tab, is the rendered template itself, followed by a separate section to display the template's rendered documentation, followed by the categories to which the template belongs.

However, the able wikicode for the template's documentation is often placed on a separate subpage of the template itself, which is then transcluded at the end of the template page. This separates the often complex template code from the documentation, making the documentation easier to and reducing the number of accidental ing errors in the template code. It also allows templates to be protected where necessary, limiting ing access to important templates' code while allowing anyone to those templates' documentation. This method is sometimes referred to as the "template-doc page pattern".

Documentation of any sort on a template page (including TemplateData) should always be enclosed by a <noinclude>...</noinclude> container, so that it does not show up when the template is used on another page.

How to create a documentation subpage[]

Put documentation in the template[]

You must put {{documentation}} when creating (publishing) a template. Then a documentation page is created with [view] [] [history] [purge] links. You can create and the template documentation clicking in this pane [] link.

Template documentation subpages using {{documentation}} are named and formatted using the following general pattern, for consistency.

Suppose your template is named Template:X. Edit the template and append the following at the end of the template code:

[--last line of your template code--]<noinclude>
{{Documentation}}
<!-- Add categories to the /doc subpage, interwikis to Wikidata, not here -->
</noinclude>

This will transclude {{documentation}} at the bottom of the template page.

Important: Make sure the opening <noinclude> begins immediately after the last character of the template code or text and not on a new line, nor with any intervening spaces. Otherwise, extra space will be inserted below the template when it is used, which is usually not wanted.

If the template is already protected, ask an administrator to do this or request an by using an {{ protected}} on the template's talk page. If documentation and categories already exist in a section, enclosed within a <noinclude>...</noinclude> container, move them into the documentation subpage (where they should be enclosed in <includeonly>...</includeonly>), as it is best not to have documentation split across two separate pages.

Automatic creation[]

Use [create] link at the bottom of the empty documentation box to automatically create a preloaded documentation subpage. Insert the documentation after the top line and categories under the appropriate comment line – leaving the comment in place, so that the layout is preserved when the page is ed in future. Related templates, policy page, projects, etc. can be linked to by adding a "See also" section. Save the subpage.

Manual creation[]

To create the documentation subpage manually, create a subpage with the name Template:X/doc. See the details at {{Documentation subpage}} or start the page by copy-pasting the following standard wikitext:

{{Documentation subpage}}
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
== Usage ==


<includeonly>{{sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->

}}</includeonly>

The top line will display a message explaining the current page and a link to the template page. Save the subpage and follow instructions in section "Use Template:Documentation".

With TemplateData[]

Instead of manually writing a lead graf and a usage table, the {{Format TemplateData}} template can do most of the job. Simply write your TemplateData in the table interface, and then wrap it into a template call like {{Format TemplateData|1=<templatedata>...</templatedata>}} at the top of the page.

Notes[]

You may wish to redirect the talk page of the /doc subpage to the talk page of the template itself. Then all talk relating to the template and its documentation will end up on the same talkpage. For example, redirect Template talk:X/doc to Template talk:X.

A documentation page can also be redirected to the /doc subpage of another template, if that covers the usage for both templates. In this case, clicking the links to view or the documentation will directly open the target of the redirect. If it is necessary to access the redirect itself (e.g. to remove the redirect and create a separate doc page), go to the template URL by clicking in the location bar at the top of your browser, and add /doc at the end.

Blank[]

To generate a blank template, which may then be copied from the documentation and pasted into another page, use:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Examples[]

To generate an instance of the template, populated with its own property names, use:

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Categories and interwiki links[]

/sandbox and /testcases[]

Before doing changes to a template it can be good to first copy the template code to a sandbox and run some testcases, since the template might be visible on thousands or even millions of pages. If you create subpages named exactly "/sandbox" and "/testcases" to a template then the green {{documentation}} box on the template auto-detects this and will show links to those pages in its header. See Wikipedia:Template sandbox and test cases for more information.

Several templates, one documentation page[]

When several templates work together or are very similar then it is often clearer and easier to maintain one single documentation page that documents them together. The simplest way to do this is to make a full documentation page at one of the templates, and then make "soft redirects" from the other templates. See, for instance, {{wrap}}.

When no documentation is needed[]

When a template as displayed will link to a page that can serve as the documentation, then separate documentation is superfluous and does not need to be created. See, for instance, a stub template, which, when displayed, will link to Wikipedia:Stub. However, this is very rare.

Tips and tricks[]

Here are some tips to facilitate writing documentations:

<includeonly>{{sandbox other||{{testcases other||
<!-- Categories below this line, please; interwikis at Wikidata -->

}}}}</includeonly>
{{Some infobox (child) template
|  child = <includeonly>yes</includeonly>
| label1 = Hello
|  data1 = World
}}<noinclude>{{documentation}}</noinclude>

See also[]