(Created page with "Templates are a very powerful feature of {{mw|MediaWiki|MediaWiki}}, but can be confusing to new users and even experienced users can have difficulty making sen...") |
|||
| (2 intermediate revisions by one other user not shown) | |||
| Line 9: | Line 9: | ||
* The '''[[Help:Templates#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:Templates#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 {{tag|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. With [[Template:Xpd]] this can be done without putting the template call twice in the wikitext. | * '''Usage examples''': specify the exact wikitext that should be used and the result that it produces. The wikitext can be enclosed in a {{tag|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. With [[Template:Xpd]] this can be done without putting the template call twice in the wikitext. | ||
* '''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. (A separate navigation template may be useful for this purpose, see: | * '''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. (A separate navigation template may be useful for this purpose, see: Template:Protection templates). | ||
* '''[[FamilySearch Wiki:Categorization|Categories]]''' and '''[[FamilySearch Wiki:InterWikimedia links|InterWikimedia links]]''', where applicable. Like the documentation, these must be within a {{tag|noinclude}} container. Many template categories are available, see: [[:Category:FamilySearch Wiki templates]] to browse through them. | * '''[[FamilySearch Wiki:Categorization|Categories]]''' and '''[[FamilySearch Wiki:InterWikimedia links|InterWikimedia links]]''', where applicable. Like the documentation, these must be within a {{tag|noinclude}} container. Many template categories are available, see: [[:Category:FamilySearch Wiki templates]] to browse through them. | ||
Template documentation is often placed in a [[FamilySearch Wiki:Subpages|subpage]] of the template itself, which is then [[FamilySearch Wiki:Transclusion|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 | Template documentation is often placed in a [[FamilySearch Wiki:Subpages|subpage]] of the template itself, which is then [[FamilySearch Wiki:Transclusion|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 FamilySearch Wiki:Protection policy 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 {{tag|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 that must be processed when displaying the template, which is [[FamilySearch Wiki:Template limits|limited]] for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason). | Documentation of any sort on a template page should always be enclosed by a {{tag|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 that must be processed when displaying the template, which is [[FamilySearch Wiki:Template limits|limited]] for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason). | ||
| Line 43: | Line 43: | ||
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: | ||
{{Colors|black|#CCC| | {{Colors|black|#CCC|var|[--last line of your template code--]}}<nowiki><noinclude> | ||
{{Documentation}} | {{Documentation}} | ||
| Line 76: | Line 76: | ||
==Several templates, one documentation page== | ==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. See for instance {{tl|wrap}}. | 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. See for instance {{tl|wrap}}. | ||
== Tips & tricks == | == Tips & tricks == | ||
| Line 85: | Line 82: | ||
* HTML tags like {{tag|ref|params=group{{=}}"note"}} can be easily inserted with {{tl|tag}}. This example is written as {{tlp|tag|ref|params{{=}}group{{=}}"note"}} | * HTML tags like {{tag|ref|params=group{{=}}"note"}} can be easily inserted with {{tl|tag}}. This example is written as {{tlp|tag|ref|params{{=}}group{{=}}"note"}} | ||
* Equals sign '''=''' can be inserted with {{tn|{{=}}}}. For example, {{tlp|Citation needed|date{{=}}1900-02-29}} is made by {{tlp|tlp|Citation needed|date{{<nowiki />=}}1900-02-29}}. Avoid the equivalent notation &#61; which is not easy to read for other editors. | * Equals sign '''=''' can be inserted with {{tn|{{=}}}}. For example, {{tlp|Citation needed|date{{=}}1900-02-29}} is made by {{tlp|tlp|Citation needed|date{{<nowiki />=}}1900-02-29}}. Avoid the equivalent notation &#61; which is not easy to read for other editors. | ||
* Don't forget the single {{tag|nowiki|s}} tag. [[<nowiki />{{tag|nowiki|s}}example]] becomes [[<nowiki />example]]* For a link to a category, use {{tl|cat}}. For example {{tlp|cat|Templates with incorrect parameter syntax}} becomes | * Don't forget the single {{tag|nowiki|s}} tag. [[<nowiki />{{tag|nowiki|s}}example]] becomes [[<nowiki />example]]* For a link to a category, use {{tl|cat}}. For example {{tlp|cat|Templates with incorrect parameter syntax}} becomes cat|Templates with incorrect parameter syntax. | ||
==See also== | ==See also== | ||
edits