RadioReference on Facebook   RadioReference on Twitter   RadioReference Blog
 
Wiki Home
Page
View source
History


Personal Tools

Search the Wiki





 

Templates-List: Documentation


Pages: Templates-List: General Use Only, Infobox-Related, Categories-Related, Sets of Related Pages, Doc.

Contents

Template Documentation

  • Templates are documented either in the template itself (when the template is short and simple), or in a "/doc" sub-page. The "/doc" sub-page link will be found at the bottom of the template, and will be the template's name with "/doc" appended to it (without quotes). Example: Template:Cat_State's documentation is located at: Template:Cat_State/doc

Templates List

  • Template-names have been chosen with the purpose of them sorting alphabetically in such a way that templates with similar purposes will naturally sort together in the list.

What to Consider When Creating or Documenting a Template

Template Name Selection

  • Template Names should:
    • be short and concise, not long and verbose. Abbreviations are often appropriate.
    • clearly reflect the type and purpose of the template.
    • be chosen so that when the names are sorted, templates of the same type and those with similar-purpose are listed together.
    • begin with a broader description and end with a more specific description
  • Examples:
Template Name
Example
Name Segment Explanation
Cat_StateFireSvcsFreq Cat the template is a categories-template (is used to create a category)
State the template is related to state-specific categories
FireSvcs the template is related to state-specific fire-services categories
Freq the template is related to state-specific fire-services categories that list frequencies.
Infobox_TRS_MultiState Infobox the template is an InfoBox-template (displays an InfoBox)
TRS the template is an InfoBox-template for a Trunked Radio System
MultiState the template is an InfoBox-template for a Trunked Radio System that spans more than one state
Tracker_DMR Tracker the template is a Tracker-template (displays warnings about certain TRS types)
DMR this Tracker-template relates to DMR/MOTOTRBO systems
USFSinCA USFS relates to the United States Forest Service
inCA relates to the United States Forest Service in California
INPH_SAFET_Pages INPH_SAFET relates to the Indiana Project Hoosier SAFE-T article(s)
Pages lists the Indiana Project Hoosier SAFE-T pages.

Template Documentation Style

  • Template Documentation style will vary based upon Template-Type.
    • A "Text..." template which uses no parameters, and only displays boilerplate text, probably will only require brief documentation at the bottom of the template itself.
    • An "InfoBox..." template which uses several parameters, will likely deserve a separate "/doc" sub-page so that the template's documentation does not clutter and oversize the template itself.
  • Style Examples and "How to" instructions are near the end of this page.

Template Documentation Content

  • What to include in the template documentation:
Attribute Details
Template's Name (case sensitive)
Template's Type
  • general-use,
  • categories-related (if so, specify which),
  • set-of-pages-related (if so, specify which)
  • etc.
Template's Purpose give a clear but concise explanation
What is expected to invoke this template?
  • another template, category, or article?
    • which one(s) specifically if known?
What should not invoke this template?
  • another template, category, or article?
    • which one(s) specifically if known?
    • And, why, if reason is not apparent.
Template's Parameters if any are used
    Parameter Name (case-sensitive)
Parameter Description provide a description if Parameter Name is unclear because it is anonymous, numbered, or specified but abbreviated
Expected Value(s)

this includes:

  • unspecified,
  • specified with no value,
  • and specific expected values
    • list the specific values
Default Value list the default value, if the default-value feature is used
Required? if a parameter-value is required, indicate so clearly.
Notes
  • Does this parameter override or hide another parameter's value. If so, explain.
  • Can this parameter be overridden or hidden by another parameter's value. If so, explain.
  • If this template is invoked by other templates, does the behavior of this template vary based upon which other template invokes this one? If so, explain in concise detail.
    • Example: Does another template cause this template to hide certain text, while a different template causes this template to display that same text?
Examples of how to invoke the template. Each example should be displayed so that it may be copy-pasted by another Wiki-editor who wants to invoke the template in that manner.
Example(s) of how... ...the template is invoked with only the required values provided, and relying on default values (This is likely to be the simplest way to invoke this template.)
Results... ...of the above technique; either show the verbatim result, or describe it in sufficient detail
Example(s) of how... ...the template is invoked with appropriate combinations of required values and specified values that override the default values
Results... ...of the above technique; either show the verbatim result, or describe it in sufficient detail
Example(s) of how... ...the template is invoked with the most complex or complete use of parameters.
Results... ...of the above technique; either show the verbatim result, or describe it in sufficient detail
Example(s) of how... ...the template can be invoked to produce unexpected but useful results
Results... ...of the above technique; either show the verbatim result, or describe it in sufficient detail
Example(s) of how... ...the template should not be invoked if the situation is an easy error to make.
Results... ...of the above technique; either show the verbatim result, or describe it in sufficient detail

How to Document a Short Simple Template

  • In the template, while in edit mode, go to the bottom of the template, after the template-definition, and place the documentation between "noinclude" tags, as illustrated below, (and then save the template):
...(end of the template-definition.)<noinclude>
 ----
 Please note: These notes and the line above do not display when this template is invoked.
 <br/><br/>

 ...place documentation here...</noinclude>
  • Caution: Please be very careful when adding the documentation at the bottom of a template, so that the template's behavior is not modified. Please make sure the "noinclude" tag immediately follows the last character of the template; otherwise unwanted spaces might be added to the template.

How to Document a Template using a "/doc" Sub-Page

  • In the template, while in edit mode, go to the bottom of the template, after the template-definition, and place the following Wiki-code between "noinclude" tags, as illustrated below, (and then save the template):
...(end of the template-definition.)<noinclude>
==Template Documentation==
*Please navigate to [[:Template:{{PAGENAME}}/doc]] for documentation about this template.</noinclude>
  • Caution: Please be very careful when adding the "/doc" documentation link at the bottom of a template, so that the template's behavior is not modified. Please make sure the "noinclude" tag immediately follows the last character of the template; otherwise unwanted spaces might be added to the template.
  • After saving the template with the above documentation link, then scroll to the bottom of the template (not in edit mode), and click on the "/doc" link to create the "/doc" page.
  • When the "/doc" page opens in edit mode, please use something similar to the following section-structure as you build the documentation page.

Documentation Sub-page for Template:(template_name)

Scope of Use

Purpose

  • [[:Template:(template_name)]] should be used to build ... (explain here what this template builds, creates, or displays)
  • [[:Template:(template_name)]] is designed to be a ("general-use" or "categories" or "set-of-related-pages")-template that... (describe this template's purpose with respect to commonality and/or uniformity of on-screen text, of categories assigned, of navigation-related links, of external resource links, etc.)

Directly Invoked By

  • [[:Template:(template_name)]] should be directly invoked only by...(describe which specific articles, categories, and/or templates should invoke this template).

Not Intended For

  • [[:Template:(template_name)]] should not be directly invoked by...(describe which specific articles, categories, and/or templates should not invoke this template).

Parameters

  • Specified values will override default values.
  • Specified values and Default values are all case-sensitive.
Parameter Name Parameter Description Expected Value(s) Default Value Notes
(first parameter)

(list only one parameter per table-row)
(parameter description if parameter name is not clear; otherwise leave table-cell blank)
  • unspecified or
  • specified with no value or
  • specified value(s) (without quotes)
    • "value 1"
    • "value 2"
    • etc.
  • list the default value, if one is used; otherwise leave table-cell blank
A value is Required (clearly indicate whether a value is required; use red font sparingly)

(list other notes here regarding this row'sparameter)
(second parameter)
(add additional row for each additional parameter)

Examples

  • The horizontal lines below separate examples for clarity and do not appear when template is invoked.


How to invoke this template for ...(idea 1)

  • {{template_name|required parameters and values}}

Result

.(either show the verbatim result, or describe it in sufficient detail)



How to invoke this template for ...(idea 2)

  • {{template_name|required parameters and different values}}

Result

.(either show the verbatim result, or describe it in sufficient detail)



How to invoke this template for ...(idea 3)

  • {{template_name|required parameters and values that override defaults}}

Result

.(either show the verbatim result, or describe it in sufficient detail)



How to invoke this template for ...(idea 4)

  • {{template_name|all parameters and values in more complex or advanced configuration}}

Result

.(either show the verbatim result, or describe it in sufficient detail)



How to invoke this template for ...(idea 5)

  • {{template_name|parameters and values that produce unexpected but useful result}}

Result

.(either show the verbatim result, or describe it in sufficient detail)



How to avoid common error(s) while invoking this template for ...(idea 6)

  • {{template_name|parameters and values to show how not to invoke this template}}

Result

.(either show the verbatim result, or describe it in sufficient detail)






Return to: [[:Template:(template_name)]]

[[Category:Documentation]]

End of "Documentation Sub-page for Template:(template_name)" Example

.



Pages: Templates-List: General Use Only, Infobox-Related, Categories-Related, Sets of Related Pages, Doc.


Copyright 2018 by RadioReference.com LLC Privacy Policy  |  Terms and Conditions