Cobhair:Documenting templates

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

Documentation should explain what a template or module does and how to use it. For templates in particular, 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.

What to include

Documentation should cover:

Categories and InterWikimedia links, where applicable. These must be within a <includeonly>…</includeonly> container. Modules cannot be categorised except through a documentation page, so this is particularly important for them. Every module should have a documentation page with a category, even if you don't write any other documentation (yet). Many categories are available, see Roinn-seòrsa:Teamplaidean and Roinn-seòrsa:Mòidealan to browse through them.
The basic purpose of the template or module: what it does and if it is not immediately obvious, why it needs to be done. If there are other templates or modules with similar names or purposes, it's a good idea to mention those, in order to reduce the chance of the wrong one being used.
The parameters of the template or module: whether they are numbered, named or optional, and if so, what the default values are and what effect they have. If a parameter can take only a limited set of values or is constrained in any way, for example, if it can only use: “yes”, “no” or a number, this should be clearly explained.
Usage examples of the template: specify the exact wikitext that should be used and the result that it produces. The wikitext can be enclosed in a <code>…</code> container, to make it clear and easy to copy, like this. If the template can be used in several different ways, with or without optional parameters, for example, provide a range of examples. A good way to do so is to transclude the template itself into the documentation a few times (i.e., use live examples), with different parameters each time and list the parameters used in each case.
Related templates or modules: if the template or module is part of a set that serves a common purpose, include links to these – in particular, ensure that every one in the series is linked from each of the others, as this makes navigation easier.

Documentation is placed in a subpage of the template or module itself, named /Documentation. Modules automatically transclude this page onto the main module page. Templates do not do this, so you need to use the template {{Documentation}}

to do this. 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 and categories. Text on the template page itself adds to the amount of text which must be processed when displaying the template, which is limited for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason).

How to create a documentation subpage

Documentation subpages should be named and formatted using the following general pattern, for consistency.

Suppose your template is named Template:X, or your module is named Mòideal:X. Create a subpage with the name Template:X/documentation or Mòideal:X/documentation. See the details at {{Documentation subpage}}

or copy-paste the following wikitext as a start for your documentation:

{{Documentation subpage}}
<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->

== Usage ==

<includeonly><!-- CATEGORIES AND INTERWIKIS HERE, THANKS -->

</includeonly>

The top line will display a message explaining the current page and a link to the template or module's main page.

Insert the documentation after the top line and categories and interwikis under the appropriate comment line – leaving the comment in place, so that the layout is preserved when the page is edited in future. Then save the subpage.

Additional information for templates

In the case of a template, you will also need to add the documentation subpage to the template itself. Return to the template's main page, Teamplaid:X, in this example. Edit the template and append the following at the end of the template code:

[--last line of your template code--]<noinclude>{{Documentation}}</noinclude>

This will transclude {{Documentation}}

at the bottom of the template page.

Important: Make sure the opening <noinclude> begins on the same line as the last character of the template code or text and not on a new line. 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 edit on the template's talk page. If documentation, categories and interwiki links already exist in a section, enclosed within a <noinclude>…</noinclude> container, move them into the documentation subpage, as it is best not to have documentation split across two separate pages.

Note that if the {{Documentation}}

template is put on the template page first, one can benefit from the preload feature to get a pre-filled doc page skeleton; if the documentation page does not exist yet, clicking the edit link on the template page will preload the contents of Teamplaid:Documentation/preload into the editbox of the /doc subpage creation.

Categories and interwiki links

To place the template or module itself into a category, add the [[Roinn-seòrsa:Category name]] code inside an <includeonly>...</includeonly> section on the documentation subpage.

To create an interwiki link for the template or module itself, add the [[Languagecode:Template name]] code inside an <includeonly>...</includeonly> section on the documentation subpage.

To place the documentation subpage into a category, add the [[Roinn-seòrsa:Category name]] code inside a <noinclude>...</noinclude> section on the documentation subpage.

To make the template place an article into a category (when the article includes the template), add the [[Roinn-seòrsa:Category name]] code inside an <includeonly>...</includeonly> section on the template page. For modules, the equivalent is to "return" the category's code as part of the returned wikitext.

Example

See the heavily-used Template:en-noun for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Template:en-noun/documentation is unprotected and can still be edited.

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 "redirects" from the other templates' documentation pages. See Template:nl-conj-wk and Template:nl-conj-st for an example of this principle.