Actions

User

Difference between revisions of "QDP2012/29"

From The RadioReference Wiki

< User:QDP2012
m
m
Line 72: Line 72:
 
*****Example: Does another template cause this template to hide certain text, while a different template causes this template to display that same text?
 
*****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.
 
**'''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 without default values (This is likely to be the simplest way to invoke this template.)
+
***'''''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 this technique
 
****'''''Results''''' of this technique
 
***'''''Example(s) of how the template is invoked''''' with appropriate combinations of required values and specified values that override the default values
 
***'''''Example(s) of how the template is invoked''''' with appropriate combinations of required values and specified values that override the default values

Revision as of 08:29, 12 September 2015


Home Prompts Move TRVA Cat Tree Links CECC Pgmg Templates

Tasks: Art, Cat, Tmp, DB
10, 13, 27, 29, 30/1
32, 43, 44,
193,194



Conv&Stds
Sandbox

Edit
PrfxIdx
..WRRR
..USBR 1
..USBR 76
..PHT
Cat List Custom
Avoid Unused
35, 36, 37, 38,

CT (C E S N) SC
Categories to be DELETED
Templates to be DELETED
Pages to be DELETED

TL (G IB C S D)
B, C, D, F, I
Tk, Tb, Ct, Tx. M, S, TO
Avoid Unused

InfoBox project related:
Template:ForTestingOnly
OLD: NEW:






.



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


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
      • Example: 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.
      • Example: Infobox_TRS_MultiState
        • Infobox = the template is an InfoBox-template (displays an InfoBox)
        • TRS = the template relates to a Trunked Radio System
        • MultiState = the template relates to a TRS that spans more than one state
      • Example: Tracker_DMR
        • Tracker = the template is a Tracker-template (displays warnings about certain TRS types)
        • DMR = this Tracker-template relates to DMR/MOTOTRBO systems
      • Example: USFSinCA
        • USFS = relates to the United States Forest Service
        • inCA = relates to the United States Forest Service in California
      • Example: INPH_SAFET_Pages
        • INPH_SAFET = relates to the Indiana Project Hoosier SAFE-T article(s)
        • Pages = lists the Indiana Project Hoosier SAFE-T pages, in this case the many RID/UID 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:
    • 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 the template -- another template, category, or article?
      • which one(s) specifically if known?
    • What should not invoke the 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
      • Parameter Description, if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated
      • Expected Value(s) of the parameter -- this includes:
        • unspecified,
        • specified with no value,
        • and specific expected values -- list the specific values
      • Default Value of the parameter, if default value feature is used
      • Is a parameter-value Required?
      • Additional Notes about the parameter
        • Does this variable override or hide another variable's value. If so, explain.
        • Can this variable be overridden or hidden by another variable'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 this technique
      • Example(s) of how the template is invoked with appropriate combinations of required values and specified values that override the default values
        • Results of this technique
      • Example(s) of how the template is invoked with the most complex or complete use of parameters.
        • Results of this technique
      • Example(s) of how the template can be invoked to produce unexpected but useful results
        • Results of this technique
      • Example(s) of how the template should not be invoked, if the situation is an easy error to make.
        • Results of this technique

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, like this, (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>

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, like this, (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>
  • 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, use something similar to the following section-structure.

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).

Paramaters

  • 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)

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]]




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