Editing BattleTechWiki:Template documentation

{{How to|BTW:TDOC|BTW:DOC}}

[[Help:Template|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 sense of the more complex ones. Templates should therefore be accompanied by '''[[w:documentation|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.

Editors should defer to official [[BTW:POLICIES |policies or guidelines]] when template documentation pages are inconsistent with established community standards and principles. Editors should also avoid "quoting" template  documentation pages as though they are policy—including this [[BTW:INFOPAGES|how-to guide]]. Template documentation pages can be written without much—if any—debate, as opposed to BattleTechWiki policies that have been [[BTW:PROPOSAL|thoroughly vetted by the community]] (see [[BTW:Local consensus]] for details).

== 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.  Include important '''limitations''', such as the lack of {{tl|Navbox visibility}} on the Mobile web site, if a template should only be used for certain countries or time periods, or other things that editors need to know before choosing to use the template. 
* 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 {{tag|code}} container, to make it clear and <code>easy to copy, like this</code>. If the template can be used in several 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.
* '''TemplateData''' tags.
* '''Related templates''': if the template is one of a series of templates, include links to these&nbsp;– 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, e.g., {{tl|Protection templates}}).
* '''Categories''' where applicable. Like the documentation, categories must be listed within a {{tag|noinclude}} container on a template, or within {{tag|includeonly|p|content={{((}}Sandbox other{{!!}}...{{))}}}} tags if placed on a documentation page. Many template categories are available, see: [[:Category:BattleTechWiki templates]] to browse through them.

== Where to place it ==
When viewing the rendered template page itself (as opposed to its wikicode), what is usually visible right under the title is the rendered template itself, followed by a separate section to display the template's rendered documentation, followed by the categories to which the template belongs. Categories and documentation of any sort on a template page (including TemplateData) should always be enclosed by ''noinclude tags'', so that they do not show up when the template is used on another page.

The editable ''wikicode'' for the template's documentation is often placed on a separate [[BattleTechWiki:Subpages|subpage]] of the template itself, which is then [[BattleTechWiki: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 and reducing the number of accidental editing errors in the template code. It also allows templates to be [[BattleTechWiki:Protection policy|protected]] where necessary, limiting editing access to important templates' code while allowing anyone to edit those templates' documentation. This method is sometimes referred to as the "template-doc page pattern".

== How to create a documentation subpage ==
=== Put documentation in the template===
You must put {{tl|documentation}} when creating (publishing) a template. Then a documentation page is created with <code>[view] [edit] [history] [purge]</code> links. You can create and edit the template documentation clicking in this pane <code>[edit]</code> link.

Template documentation subpages using {{tl|documentation}} are named and formatted using the following general pattern, for consistency.

'''Important''': Make sure the opening {{tag|noinclude|o}} begins immediately after the last character of the template code or text and ''not'' on a new line, nor with any intervening spaces. Otherwise, extra space will be inserted below the template when it is used, which is usually not wanted.

If documentation and categories already exist in a section, enclosed within a {{tag|noinclude}} container, move them into the documentation subpage (where they should be enclosed in {{tag|includeonly}}), as it is best not to have documentation split across two separate pages.

=== Automatic creation ===

Use <code><nowiki>[create]</nowiki></code> link at the bottom of the empty documentation box to automatically create a [[w:Preload|preloaded]] documentation subpage. Insert the documentation after the top line and categories under the appropriate comment line&nbsp;– leaving the comment in place, so that the layout is preserved when the page is edited in future. Related templates, policy page, projects, etc. can be linked to by adding a "See also" section. Save the subpage.

=== Manual creation ===
To create the documentation subpage manually, create a subpage with the name <code>Template:X/doc</code>. See the details at {{tl|Documentation subpage}} or start the page by copy-pasting the following standard wikitext:
<!---------------------------------------------------------------------------------------
  Note: The following code block is copy-pasted from [[Template:Documentation/preload]];
    check it periodically for updates and copy it here again if necessary, amending its
    "<include<includeonly></includeonly>only>" accordingly.
 ---------------------------------------------------------------------------------------->
<syntaxhighlight lang="wikitext" style="overflow:auto;">
{{Documentation subpage}}
== Usage ==


<includeonly>{{Sandbox other||
<!-- Categories below this line -->

}}</includeonly>
</syntaxhighlight>

The top line will display a message explaining the current page and a link to the template page. Save the subpage and follow instructions in section "[[#Use Template:Documentation|Use Template:Documentation]]".

=== With TemplateData ===
Instead of manually writing a lead graf and a usage table, the {{tl|Format TemplateData}} template can do most of the job. Simply write your TemplateData in the table interface, and then wrap it into a template call like <code><nowiki>{{Format TemplateData|1=<templatedata>...</templatedata>}}</nowiki></code> at the top of the page.

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

A documentation page can also be redirected to the /doc subpage of another template, if that covers the usage for both templates. In this case, clicking the links to view or edit the documentation will directly open the target of the redirect. If it is necessary to access the redirect itself (e.g. to remove the redirect and create a separate doc page), go to the template URL by clicking in the location bar at the top of your browser, and add /doc at the end.

== Blank ==

To generate a blank template, which may then be copied from the documentation and pasted into another page, use:

:<code><nowiki>{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}</nowiki></code>

== Examples ==

To generate an instance of the template, populated with its own property names, use:

:<code><nowiki>{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}</nowiki></code>

== Categories and interwiki links ==
* '''To place the template itself into a category''', add the <code><nowiki>[[Category:Category name]]</nowiki></code> code inside an {{tag|includeonly}} section on the ''doc'' subpage.
* '''To create an interwiki link for the template itself'''
* '''To place the ''doc'' subpage into a category''', add the <code><nowiki>[[Category:Category name]]</nowiki></code> code inside a {{tag|noinclude}} section on the ''doc'' subpage.
* '''To make the template place an article into a category''' (when the article includes the template), add the <code><nowiki>[[Category:Category name]]</nowiki></code> code inside an {{tag|includeonly}} section on the template page. Exact placement within the template code may affect how the category code is executed.
<!-- -->
<!-- ==Example==
See the heavily-used [[Template:cite web]] for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, [[Template:cite web/doc]] is unprotected and can still be edited.
 --><!-- The preceding section appears out dated at this time. I left it here so as to hold a place for an updated example. Template:cite web now uses lua. Lua is a programming language now available via the Scribunto MediaWiki extension. -->

== /sandbox and /testcases ==
Before doing changes to a template it can be good to first copy the template code to a sandbox and run some testcases, since the template might be visible on thousands or even millions of pages. If you create subpages named exactly "'''/sandbox'''" and "'''/testcases'''" to a template then the green {{tlc|documentation}} box on the template auto-detects this and will show links to those pages in its header.  See [[BattleTechWiki:Template sandbox and test cases]] for more information.

== 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. See, for instance: {{tl|wrap}}.

==Directly on a template page==
When a documentation subpage has not been created, and the {{tlx|documentation}} template is being used with a {{para|content}} parameter on the actual template page, then to place the template itself into a category, add {{elc|Category:Category name}} inside the documentation template, after the content. For example, for placement on the actual template page:

<syntaxhighlight lang="wikitext" style="overflow:auto;">
<!--Last line of your template code--><noinclude>
{{Documentation
 | content =
<!-- template documentation -->

[[Category:Category name]]
[[Category:Category name2]]
}}</noinclude>
</syntaxhighlight>

== {{Anchor|When no documentation needed}} When no documentation is needed ==
<!-- This Anchor tag serves to provide a permanent target for incoming section links. Please do not move it out of the section heading, even though it disrupts edit summary generation (you can manually fix the edit summary before you save your changes). Please do not modify it, even if you modify the section title. It is always best to anchor an old section header that has been changed so that links to it won't be broken. See [[Template:Anchor]] for details. (This text: [[Template:Anchor comment]]) -->
When a template as displayed will link to a page that can serve as the documentation, then separate documentation is superfluous and does not need to be created. For instance, a stub template, using the {{tl|asbox}} template as a base, will already display pre-loaded common documentation for all stub templates using that template, and will not need additional documentation.

== See also ==
* {{tl|Documentation}} – 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
* [[mw:Help:Template#Noinclude, includeonly, and onlyinclude|{{tag|noinclude|o}} and {{tag|includeonly|o}}]]
* {{tl|Improve documentation}}
* {{tl|Tag}} – global use
* [[:Category:Documentation assistance templates]]


[[Category:Template documentation|*]]
[[Category:Template help]]