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 | + | ***Is a parameter-value '''''Required'''''? |
| − | *** | + | ***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 23: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 | |||
.
| 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 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.
- Example: Cat_StateFireSvcsFreq
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
- 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.)
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. |