Template:Documentation/doc

Purpose
This template is intended for helping to document templates.

As a good practice, template documentation is often placed in a subpage (called "doc") 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 edit. It also allows templates to be protected where necessary, while allowing anyone to edit the documentation, categories, and interwiki links. This method is sometimes referred to as the "template doc page pattern".

This template is dealing with the template page part of the job – the documentation subpage part being dealt with by the Documentation subpage template.

It displays a message box about template documentation and then loads into a blue frame the content of the /doc subpage (i.e. the page whose name is the name of the template postfixed by ). Note that if the documentation subpage doesn't exist, the frame isn't displayed and the message box indicates that documentation is missing. The template is also added to the Undocumented templates category.

Usage
This template is used without any parameters.

Normally, it is placed at the bottom of the template being documented, within  tags:

Then you have to create the /doc subpage in which one can write the documentation of it (see Template:Documentation subpage). Categories and interwiki links that apply to the template itself should be added to the bottom of the /doc subpage, inside  tags.

It is important to note that there is no space between the end of the template code and the opening  tag. The contrary would cause extra space on pages where the template is used, which would be likely to break how the template works.

Moreover, many templates are not standalone or are not meant for being called without any parameters. As a consequence, it is a good practice to include the template code within  tags to prevent the template from being printed when it isn't transcluded (i.e. when a user visits the template page instead of the page using it). However, since users may want to know what does the template look like when used, make sure to provide output examples in the documentation.

To summarize, here is a good structure of a template page:

Examples
This template is documented using itself. The page you are viewing illustrates how the documentation is displayed in each template page. As an example of how this documentation is displayed when using this template, see the |template page corresponding to it.

Related templates

 * Documentation subpage