Editing NearReality:Template policy

{{shortcut|RS:TPOL}}
{{Nutshell|When you create a template, if it's anything more than some static wikicode, document it. Other editors will be less confused.}}

Templates are very often used on the Old School RuneScape Wiki, and they can be anything from static wikicode, shown on a page whenever it's placed on it, to extremely complex calculations and dynamic tables.

When you [[Help:Template|create a template]], you may have it use parameters to insert some text defined by the editor who uses your template, or [[mw:Help:Magic words|have it use magic words]] so it acts differently according to the page it's used on. If a template uses parameters or magic words beyond just displaying text, it should have documentation.

==Basic templates don't need documentation==

If, when an editor invokes a template, what's shown never changes under any circumstances, the template's page may simply show this content without any usage information. An editor then knows that they can use the template by entering its name, enclosed in <code><nowiki>{{</nowiki></code> and <code><nowiki>}}</nowiki></code>.

==Documentation==
To create a template's documentation page, go to the template's page, for example [[Template:Sandbox]], and add <code>/doc</code> at the end of the URL. You will then be ready to edit the documentation page.

===Marking the documentation page===
The first thing in a template documentation page should be a transclusion of the {{t|Documentation}} template, which has the effect of marking the documentation page as such on the page of the template to be documented.

[[Template:Documentation/doc|See Documentation's documentation here.]]

===High-level summary===
The next thing should be a high-level summary of the template's results. For example, "'''Template:Example''' displays a table of all available Dungeoneering items made with a certain material."

===Parameter descriptions===
Templates that use parameters need to have a summary of how to specify and use each of the parameters. A template's parameters may be numbered or named, or both. Additionally, the value may need to be in a certain format for the template to use it; this format also needs to be mentioned. [[Template:Coins]], for example, expects its parameter to have no commas.

===Numbered parameters===
[[Template:FloorNumber]] is an example of a template that uses a numbered parameter. Since it has only one numbered parameter, it does not need to specify which parameter comes first, but its documentation needs to state that the parameter has no ''name='' prefix. Otherwise, an editor could try <code><nowiki>{{</nowiki>[[Template:FloorNumber|FloorNumber]]|floor=1<nowiki>}}</nowiki></code> and fail to produce the correct result.

[[Template:FloorNumber/doc|See FloorNumber's documentation here.]]

===Named parameters===
Most infobox templates on the wiki are examples of templates that use named parameters. Each parameter produces a cell in the infobox's table, and their order doesn't matter, only their presence in the parameter list. The function of each named parameter should be in its own section in the documentation page. The name of the section should match the name of the parameter; for example, documenting <code><nowiki>{{</nowiki>Foo|bar=baz<nowiki>{{</nowiki></code> would be at Template:Foo/doc, starting with <code><nowiki>== bar ==</nowiki></code>.

[[Template:Infobox Item/doc|See Infobox Item's documentation here.]]

====Templates with lots of named parameters====
If a template has a lot of named parameters, like [[Template:Infobox Item]], it may be helpful to provide an invocation of the template with all of its parameters already present but not filled in, inside a <code>&lt;pre&gt;</code> tag. This way, an editor who knows what the template's name is but not all of its parameters can visit its page and copy-paste an invocation on a page.

===Usage examples===
Templates with parameters should have, following the description of each parameter, a few examples to demonstrate the combinations available and the results they produce.

For example, [[Template:Block]] can accept a numbered parameter, but its presence is not required; [[Template:Closure]], to request the closure of a discussion, can accept one or two parameters, and the meaning of its first parameter is special when it is in a list of recognised words.

See [[Template:Block/doc|Block's documentation]] and [[Template:Closure/doc|Closure's documentation]].

===Exceptions===
Some templates are unique in that they do not need their own documentation subpage or should have a different formatting than the usual documentation, due to unique circumstances surrounding these templates. In these cases, the following exceptions will apply.

====Userboxes====
Userboxes should link to the [[Template:Userbox/doc|userbox template documentation]].  This is due to the fact that all documentation for userboxes would essentially be the same. Linking to their parent template's documentation allows a uniform format for them. In these cases, the following code should be used.

<pre><noinclude>{{Userbox/doc}}</noinclude></pre>

====Navboxes====
Navboxes do not need their own documentation. Navboxes do not change, and only display a navigational template. As a result, they should not have their own documentation. Instead, Navboxes should use the standard Navbox documentation {{t|Navbox/doc}}.

====Signatures====
Signatures are similar to userboxes, in that they should have a uniform documentation. However, signatures tend to change on a semi-regular basis, and only display a line of text. As a result, signatures should '''not''' have their own documentation.

====Documentation====
Documentation subpages are technically templates themselves. However, they should not have their own documentation. Doing so would result in an infinite number of subpages.

==Linking the documentation and the template==
After you are done creating a template documentation page (i.e. a /doc subpage), go back to the template itself and add this to its wikicode:
<pre><noinclude>{{/doc}}</noinclude></pre>

This will show the "Template documentation" section under the template.

==See also==
* [[RuneScape:Templates]], a non-exhaustive list of templates available
* [[RuneScape:Personal Templates]]

{{Policies & Guidelines}}