No edit summary |
DSquirrelGM (talk | contribs) (→Editing templates: replaced: tt> → code> (2)) |
||
(9 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | Templates are powerful tools for simplifying many tasks, organizing work, standardizing content, and otherwise improving the wiki. However, they also have potential drawbacks and limitations which should be kept in mind when developing new templates and using existing ones. Please follow the guidelines listed below when creating and editing templates |
+ | Templates are powerful tools for simplifying many tasks, organizing work, standardizing content, and otherwise improving the wiki. However, they also have potential drawbacks and limitations which should be kept in mind when developing new templates and using existing ones. Please follow the guidelines listed below when creating and editing templates. |
== Problems and questions == |
== Problems and questions == |
||
− | Templates on this wiki |
+ | Templates (and [[mw:Extension:Scribunto|Scribunto]] modules, which some of them may use) on this wiki are maintained by the community. All questions and issues regarding templates may be directed to the specific template or module's talk page or the [[Project:CD|centralized discussion board]]. |
+ | == Most important thing == |
||
− | == Read this before making any changes to templates == |
||
− | + | Many templates are widely used across the wiki, so please be careful when editing those templates. Breaking such templates can lead to serious consequences. If you don't know what you're doing, ask more experienced editors first. Of course, the most used templates (such as {{Tl|Gc}} and {{Tl|Infobox}}) are already protected to prevent edits by unauthorized users, so you may need to ask other editors anyway. |
|
== Creating templates == |
== Creating templates == |
||
− | Before creating any templates, please make sure that no template similar to yours exists. A [[Project:All templates|full list]] with a brief description can be found on the wiki. |
+ | Before creating any templates, please make sure that no template similar to yours exists. A [[Project:All templates|full list]] with a brief description can be found on the wiki. |
− | When creating templates, |
+ | When creating templates, keep your code simple but effective and efficient. Making sure to document your template; documentation is required for every template (see [[#Documenting templates|Documenting templates]]). To include the documentation in the template page, add <code><nowiki><noinclude></nowiki>{{Tl|Documentation}}<nowiki></noinclude></nowiki></code> on the last line of your template. Don't put it on a new line, or the new line may be included in the template itself. Note some templates (such as {{Tl|Stub}} or the navboxes) have shared documentation that can be taken advantage of. Lastly, make sure to test your template! |
After creating the template, please update the [[Project:All templates|list of templates]] with your new template with an accompanying description. |
After creating the template, please update the [[Project:All templates|list of templates]] with your new template with an accompanying description. |
||
== Editing templates == |
== Editing templates == |
||
− | When editing templates, |
+ | When editing templates, make sure that all brackets are balanced. It is recommended you use the preview feature (removing <code><includeonly></code> tags when needed) to make sure it works. An edit summary is usually a good idea. |
− | If your change |
+ | If your change adds or removes parameters or changes the behavior of the template, you must also update the template documentation. Also, if the invocations of the template no longer function as a result of your change, make sure to work to fix that; if the template has only been used a few times, fixing it manually isn't too hard, although if the template is more used, some editors have bots that could assist in large-scale changes. |
− | |||
− | Metatemplates are templates which are intended to be used in other templates and sometimes templates are completely built out of metatemplates, always discuss your change on the template's talk page before you make changes to such templates. |
||
== Documenting templates == |
== Documenting templates == |
||
− | Template documentation should always be up-to-date and should be updated when templates are modified |
+ | Template documentation should always be up-to-date and should be updated when templates are modified. |
== Documentation format == |
== Documentation format == |
||
Line 33: | Line 31: | ||
=== Documentation boilerplate === |
=== Documentation boilerplate === |
||
− | All documentation should start with {{Tl|Doc/Start}} and should end with {{Tl|Doc/End}}. |
+ | All documentation should start with {{Tl|Doc/Start}} and should end with {{Tl|Doc/End|<nowiki>{{subst:FULLPAGENAME}}</nowiki>}}. |
=== Template purpose === |
=== Template purpose === |
||
− | The |
+ | The lead section of the template documentation should be a brief introduction purpose of the template, an accompanying '''"Usage"''' section to explain in detail of the purpose of the template. This section could also include how the templates works to assist editors that wish to edit the template. |
=== Template parameters === |
=== Template parameters === |
||
Line 43: | Line 41: | ||
which produces: |
which produces: |
||
* '''<Parameter name>''': ''(Optional or Default:<value>)'' <Description> |
* '''<Parameter name>''': ''(Optional or Default:<value>)'' <Description> |
||
− | Please omit the optional and default section if the parameter is required, only one of ''"Optional"'' and ''"Default:<value>"'' should exist, since if a default value is set |
+ | Please omit the optional and default section if the parameter is required, only one of ''"Optional"'' and ''"Default:<value>"'' should exist, since if a default value is set (the parameter is optional). |
=== Template examples === |
=== Template examples === |
||
− | The following section should be examples of some general and common usage of the template |
+ | The following section should be examples of some general and common usage of the template; this section can be omitted if examples cannot be displayed. Additional formatting, rows, and columns can be added if desired. The examples could be in the following formats depending on the size or properties: |
==== Format 1 ==== |
==== Format 1 ==== |
||
===== Code ===== |
===== Code ===== |
||
<pre><Description> |
<pre><Description> |
||
<pre><Code></pre> |
<pre><Code></pre> |
||
− | produces: |
+ | produces:<br /> |
<Template call></pre> |
<Template call></pre> |
||
===== Result ===== |
===== Result ===== |
||
<Description> |
<Description> |
||
<pre><Code></pre> |
<pre><Code></pre> |
||
− | produces: |
+ | produces:<br /> |
<Template call> |
<Template call> |
||
− | ===== Notes ===== |
||
− | * A line break can be added after the "produces:" if desired. |
||
==== Format 2 ==== |
==== Format 2 ==== |
||
===== Code ===== |
===== Code ===== |
||
Line 74: | Line 70: | ||
| <Code> || <Result> |
| <Code> || <Result> |
||
|} |
|} |
||
− | ===== Notes ===== |
||
− | * Additional formatting, rows, and columns can be added if desired. |
||
=== Related templates === |
=== Related templates === |
||
− | The last part of the documentation should include a list of related templates and a brief description of them. This part should be split into two sections, sub-templates or child-templates in a section named |
+ | The last part of the documentation should include a list of related templates and a brief description of them. This part should be split into two sections, sub-templates or child-templates in a section named "Sub-templates", templates with similar purpose in a section named "See also". Closely related templates could share the same documentation of other templates by using: |
<pre>{{Documentation|<Template name>}}</pre> |
<pre>{{Documentation|<Template name>}}</pre> |
||
=== Template categories === |
=== Template categories === |
||
− | Include categories in the template documentation with |
+ | Include categories in the template documentation with {{Tl|TC}}, add the code: {{Tlx|TC|<Category name>}} to the bottom of the documentation before the {{Tl|Doc/End}}. |
+ | |||
{{Navbox portals}} |
{{Navbox portals}} |
||
+ | |||
[[Category:Guidelines]] |
[[Category:Guidelines]] |
||
+ | |||
+ | <languages /> |
Latest revision as of 13:21, 25 November 2018
Templates are powerful tools for simplifying many tasks, organizing work, standardizing content, and otherwise improving the wiki. However, they also have potential drawbacks and limitations which should be kept in mind when developing new templates and using existing ones. Please follow the guidelines listed below when creating and editing templates.
Problems and questions
Templates (and Scribunto modules, which some of them may use) on this wiki are maintained by the community. All questions and issues regarding templates may be directed to the specific template or module's talk page or the centralized discussion board.
Most important thing
Many templates are widely used across the wiki, so please be careful when editing those templates. Breaking such templates can lead to serious consequences. If you don't know what you're doing, ask more experienced editors first. Of course, the most used templates (such as {{Gc}}
and {{Infobox}}
) are already protected to prevent edits by unauthorized users, so you may need to ask other editors anyway.
Creating templates
Before creating any templates, please make sure that no template similar to yours exists. A full list with a brief description can be found on the wiki.
When creating templates, keep your code simple but effective and efficient. Making sure to document your template; documentation is required for every template (see Documenting templates). To include the documentation in the template page, add <noinclude>
on the last line of your template. Don't put it on a new line, or the new line may be included in the template itself. Note some templates (such as {{Documentation}}
</noinclude>{{Stub}}
or the navboxes) have shared documentation that can be taken advantage of. Lastly, make sure to test your template!
After creating the template, please update the list of templates with your new template with an accompanying description.
Editing templates
When editing templates, make sure that all brackets are balanced. It is recommended you use the preview feature (removing <includeonly>
tags when needed) to make sure it works. An edit summary is usually a good idea.
If your change adds or removes parameters or changes the behavior of the template, you must also update the template documentation. Also, if the invocations of the template no longer function as a result of your change, make sure to work to fix that; if the template has only been used a few times, fixing it manually isn't too hard, although if the template is more used, some editors have bots that could assist in large-scale changes.
Documenting templates
Template documentation should always be up-to-date and should be updated when templates are modified.
Documentation format
Template documentation should generally include the following information in the order specified below:
- The purpose of the template.
- The parameters of the template.
- Usage examples of the template.
- Related templates.
- Categories.
Documentation boilerplate
All documentation should start with {{Doc/Start}}
and should end with {{Doc/End|{{subst:FULLPAGENAME}}}}
.
Template purpose
The lead section of the template documentation should be a brief introduction purpose of the template, an accompanying "Usage" section to explain in detail of the purpose of the template. This section could also include how the templates works to assist editors that wish to edit the template.
Template parameters
The second section of the template should be an unorded list of parameters and their default value, properties and description in the following format:
* '''<Parameter name>''': ''(Optional or Default:<value>)'' <Description>
which produces:
- <Parameter name>: (Optional or Default:<value>) <Description>
Please omit the optional and default section if the parameter is required, only one of "Optional" and "Default:<value>" should exist, since if a default value is set (the parameter is optional).
Template examples
The following section should be examples of some general and common usage of the template; this section can be omitted if examples cannot be displayed. Additional formatting, rows, and columns can be added if desired. The examples could be in the following formats depending on the size or properties:
Format 1
Code
<Description> <pre><Code></pre> produces:<br /> <Template call>
Result
<Description>
<Code>
produces:
<Template call>
Format 2
Code
{| class="wikitable" ! Code !! Result |- | <Code> || <Result> |}
Result
Code | Result |
---|---|
<Code> | <Result> |
Related templates
The last part of the documentation should include a list of related templates and a brief description of them. This part should be split into two sections, sub-templates or child-templates in a section named "Sub-templates", templates with similar purpose in a section named "See also". Closely related templates could share the same documentation of other templates by using:
{{Documentation|<Template name>}}
Template categories
Include categories in the template documentation with {{TC}}
, add the code: {{TC|<Category name>}}
to the bottom of the documentation before the {{Doc/End}}
.