Memory Alpha
Register
Memory Alpha
m (Robot: Automated text replacement (-“ +") !!wikia-credits fix!!)
m (Bot: Automated text replacement (-– +–) !!wikia-credits fix!!)
Line 2: Line 2:
 
[[Help:Template|Templates]] are a very powerful feature of {{w|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 '''{{w|documentation}}''' to improve usability.
 
[[Help:Template|Templates]] are a very powerful feature of {{w|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 '''{{w|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.
+
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.
   
 
==What to include==
 
==What to include==
Line 10: Line 10:
 
* The '''[[Help:Template#Parameters|parameters]]''' of the template: 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.
 
* The '''[[Help:Template#Parameters|parameters]]''' of the template: 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''': specify the exact wikitext that should be used and the result that it produces. The wikitext can be enclosed in a <code><nowiki><code>...</code></nowiki></code> container, to make it clear and <code>easy to copy, like this</code>. 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.
 
* '''Usage examples''': specify the exact wikitext that should be used and the result that it produces. The wikitext can be enclosed in a <code><nowiki><code>...</code></nowiki></code> container, to make it clear and <code>easy to copy, like this</code>. 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''': if the template is one of a series of templates, include links to these in particular, ensure that every template in the series is linked from each of the others, as this makes navigation easier.
+
* '''Related templates''': if the template is one of a series of templates, include links to these &ndash; in particular, ensure that every template in the series is linked from each of the others, as this makes navigation easier.
 
* '''[[Memory Alpha:Categories|Categories]]''' and '''[[Help:Interwiki|Interwiki links]]''', where applicable. Like the documentation, these must be within a <code><nowiki>&lt;noinclude>...&lt;/noinclude></nowiki></code> container. Many template categories are available, see [[:Category: Memory Alpha templates]] to browse through them.
 
* '''[[Memory Alpha:Categories|Categories]]''' and '''[[Help:Interwiki|Interwiki links]]''', where applicable. Like the documentation, these must be within a <code><nowiki>&lt;noinclude>...&lt;/noinclude></nowiki></code> container. Many template categories are available, see [[:Category: Memory Alpha templates]] to browse through them.
   
Line 35: Line 35:
 
The top line will display a message explaining the current page and a link to the template page.
 
The top line will display a message explaining the current page and a link to the template 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. The subpage template sets a <nowiki>{{DEFAULTSORT:{{PAGENAME}}}}</nowiki>, ensuring that a <code>Template:X</code> will be properly sorted at "X" and not "T", it is thus not useful or desirable to add a <nowiki>{{PAGENAME}}</nowiki> sort key to the categories.
+
Insert the documentation after the top line and categories and interwikis under the appropriate comment line &ndash; leaving the comment in place, so that the layout is preserved when the page is edited in future. The subpage template sets a <nowiki>{{DEFAULTSORT:{{PAGENAME}}}}</nowiki>, ensuring that a <code>Template:X</code> will be properly sorted at "X" and not "T", it is thus not useful or desirable to add a <nowiki>{{PAGENAME}}</nowiki> sort key to the categories.
   
 
Save the subpage and return to the template itself, <code>Template:X</code>, in this example. Edit the template and append the following at the end of the template code:
 
Save the subpage and return to the template itself, <code>Template:X</code>, in this example. Edit the template and append the following at the end of the template code:
Line 72: Line 72:
   
 
==See also==
 
==See also==
* {{tl|Documentation}} Transcludes the documentation on the template page, and provides documentation view, edit and history links
+
* {{tl|Documentation}} &ndash; Transcludes the documentation on the template page, and provides documentation view, edit and history links
* {{tl|Documentation subpage}} Explains that what follows is documentation, and links to the documented page
+
* {{tl|Documentation subpage}} &ndash; Explains that what follows is documentation, and links to the documented page
 
* [[m:Help:Templates#Noinclude, includeonly, and onlyinclude|<tt>&lt;noinclude&gt;</tt> and <tt>&lt;includeonly&gt;</tt>]]
 
* [[m:Help:Templates#Noinclude, includeonly, and onlyinclude|<tt>&lt;noinclude&gt;</tt> and <tt>&lt;includeonly&gt;</tt>]]
   

Revision as of 15:13, 5 November 2010

Memory Alpha  AboutPolicies and guidelinesTemplate → 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.

What to include

Template documentation should cover:

  • The basic purpose of the template: what it does and, if it is not immediately obvious, why it needs to be done. If there are other templates 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: 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: 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: if the template is one of a series of templates, include links to these – in particular, ensure that every template in the series is linked from each of the others, as this makes navigation easier.
  • Categories and Interwiki links, where applicable. Like the documentation, these must be within a <noinclude>...</noinclude> container. Many template categories are available, see Category: Memory Alpha templates to browse through them.

Template documentation is often placed in a 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 edit. It also allows templates to be protected where necessary, while allowing anyone to edit the documentation. This method is sometimes referred to as the "template doc page pattern".

Documentation of any sort on a template page should always be enclosed by a <noinclude>...</noinclude> container, so that it does not show up when the template is used on another page. 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

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

Suppose your template is named Template:X. Create a subpage with the name Template:X/doc. 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 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. The subpage template sets a {{DEFAULTSORT:{{PAGENAME}}}}, ensuring that a Template:X will be properly sorted at "X" and not "T", it is thus not useful or desirable to add a {{PAGENAME}} sort key to the categories.

Save the subpage and return to the template itself, Template: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}}
<!-- PLEASE ADD THIS TEMPLATE'S CATEGORIES AND INTERWIKIS TO THE /doc SUBPAGE -->
</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.

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 talk page. For example, redirect Template talk:X/doc to Template talk:X.

Categories and interwiki links

  • To place the template itself into a category, add the [[Category:Category name]] code inside an <includeonly>...</includeonly> section on the doc subpage.
  • To create an interwiki link for the template itself, add the [[Languagecode:Template name]] code inside an <includeonly>...</includeonly> section on the doc subpage.
  • To place the doc subpage into a category, add the [[Category:Category name]] code inside a <noinclude>...</noinclude> section on the doc subpage.
  • To make the template place an article into a category (when the article includes the template), add the [[Category:Category name]] code inside an <includeonly>...</includeonly> section on the template page.

Example

See the heavily-used {{Wikipedia}} for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Template:Wikipedia/doc 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 "soft redirects" from the other templates, that is, to make very short documentation pages at the other templates that have only one or two sentences that states where the full documentation can be found and link to it.

Stub templates

Stub templates are one of the very rare forms of template which do not generally have documentation. As all stub templates operate in identical ways, they could theoretically be linked to one documentation page giving instruction for their use. This is, however, regarded as superfluous, since all stub templates already contain a link to Memory Alpha: Find or fix a stub, which more thoroughly covers all the information that would normally be covered by a documentation page.

See also