Actions

User

Difference between revisions of "QDP2012/29"

From The RadioReference Wiki

< User:QDP2012
m
m
Line 31: Line 31:
 
===Template Documentation Content===
 
===Template Documentation Content===
 
*What to Include in the Template Documentation:
 
*What to Include in the Template Documentation:
**Template's Name
+
**'''Template's Name''' (case sensitive)
**Template's Type
+
**'''Template's Type'''
 
***general-use,
 
***general-use,
 
***categories-related (if so, specify which),
 
***categories-related (if so, specify which),
 
***set-of-pages-related (if so, specify which)
 
***set-of-pages-related (if so, specify which)
 
***etc.
 
***etc.
**Template's Purpose -- give a clear but concise explanation
+
**'''Template's Purpose''' -- give a clear but concise explanation
**What is expected to invoke the template -- another template, category, or article?
+
**'''What is expected to invoke the template''' -- another template, category, or article?
 
***which one(s) specifically if known?   
 
***which one(s) specifically if known?   
**What should not invoke the template -- another template, category, or article?
+
**'''What should not invoke the template''' -- another template, category, or article?
 
***which one(s) specifically if known?
 
***which one(s) specifically if known?
 
***And, why, if reason is not apparent.
 
***And, why, if reason is not apparent.
**Template's Parameters, if any are used
+
**'''Template's Parameters''', if any are used
***Parameter Name
+
***'''''Parameter Name'''''
***Parameter Description, if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated
+
***'''''Parameter Description''''', if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated
***Expected Value(s) of the parameter -- this includes:
+
***'''''Expected Value(s)''''' of the parameter -- this includes:
 
****unspecified,  
 
****unspecified,  
 
****specified with no value,  
 
****specified with no value,  
 
****and specific expected values -- list the specific values
 
****and specific expected values -- list the specific values
***Default Value of the parameter, if default value is used
+
***'''''Default Value''''' of the parameter, if default value is used
***Is a parameter-value required?
+
***Is a parameter-value '''''Required'''''?
***Any other notes about the parameter
+
***Additional '''''Notes''''' about the parameter
****Does this variable override or hide another variable's value.  If so, explain.
+
****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.
+
****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 template vary based upon which other template invokes this one?  If so, which one(s) and how?
 
****If this template is invoked by other templates, does the behavior of template vary based upon which other template invokes this one?  If so, which one(s) and how?
**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 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 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
****Results of this technique
+
****'''''Results''''' of this technique
***Example(s) of how the template is invoked with the most complex or complete use of parameters.
+
***'''''Example(s) of how the template is invoked''''' with the most complex or complete use of parameters.
****Results of this technique
+
****'''''Results''''' of this technique
***Example(s) of how the template can be invoked to produce unexpected but useful results
+
***'''''Example(s) of how the template can be invoked''''' to produce unexpected but useful results
****Results of this technique
+
****'''''Results''''' of this technique
***Example(s) of how the template should not be invoked, if the situation is an easy error to make.
+
***'''''Example(s) of how the template should not be invoked''''', if the situation is an easy error to make.
****Results of this technique
+
****'''''Results''''' of this technique
  
 
==How to Document a Short Simple Template==
 
==How to Document a Short Simple Template==

Revision as of 22:37, 11 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 must be chosen with these ideas in mind:
    • Template Names should be short and concise, not long and verbose. Abbreviations are often appropriate.
    • Template Names should clearly reflect the purpose of the template.
    • Template Names should be chosen so that they sort together with similar-purpose templates.
    • Template Names should follow the standard naming convention so that the name begins with a broader description and ends with a more specific description
      • Example: Cat_StateFireSvcsFreq
        • Cat = the template is related to the Wiki's categories
        • 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.

Template Documentation Style

  • Template Documentation 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.

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 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 template vary based upon which other template invokes this one? If so, which one(s) and how?
    • 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 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

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




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