Difference between revisions of "QDP2012/29"
From The RadioReference Wiki
< User:QDP2012
m |
m |
||
Line 58: | Line 58: | ||
===Template Documentation Content=== | ===Template Documentation Content=== | ||
*What to Include in the Template Documentation: | *What to Include in the Template Documentation: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
{| {{table}} width="100%" | {| {{table}} width="100%" | ||
|- bgcolor="lightgrey" | | |- bgcolor="lightgrey" | | ||
Line 122: | Line 83: | ||
| colspan="2" | '''Template's Parameters''' || if any are used | | colspan="2" | '''Template's Parameters''' || if any are used | ||
|- | |- | ||
− | || ||'''''Parameter Name''''' || (case-sensitive) | + | | bgcolor="lightgrey" | ||'''''Parameter Name''''' || (case-sensitive) |
|- | |- | ||
− | || ||'''''Parameter Description''''' || if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated | + | | bgcolor="lightgrey" | ||'''''Parameter Description''''' || if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated |
|- | |- | ||
− | || ||'''''Expected Value(s)''''' || | + | | bgcolor="lightgrey" | ||'''''Expected Value(s)''''' || |
this includes: | this includes: | ||
*unspecified, | *unspecified, | ||
Line 132: | Line 93: | ||
*and specific expected values -- list the specific values | *and specific expected values -- list the specific values | ||
|- | |- | ||
− | || ||'''''Default Value''''' ||if default value feature is used | + | | bgcolor="lightgrey" | ||'''''Default Value''''' ||if default value feature is used |
|- | |- | ||
− | || ||Is a parameter-value '''''Required'''''? || | + | | bgcolor="lightgrey" | ||Is a parameter-value '''''Required'''''? || |
|- | |- | ||
− | || ||Additional '''''Notes''''' about the parameter || | + | | bgcolor="lightgrey" | ||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. | ||
Line 144: | Line 105: | ||
| colspan="2" | '''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. | | colspan="2" | '''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.) | + | | bgcolor="lightgrey" | || '''''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 | + | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique |
|- | |- | ||
− | || || '''''Example(s) of how...''''' || ...the template is invoked with appropriate combinations of required values and specified values that override the default values | + | | bgcolor="lightgrey" | || '''''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 | + | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique |
|- | |- | ||
− | || || '''''Example(s) of how...''''' || ...the template is invoked with the most complex or complete use of parameters. | + | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template is invoked with the most complex or complete use of parameters. |
|- | |- | ||
− | || || '''''Results...''''' || ...of the above technique | + | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique |
|- | |- | ||
− | || || '''''Example(s) of how...''''' || ...the template can be invoked to produce unexpected but useful results | + | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template can be invoked to produce unexpected but useful results |
|- | |- | ||
− | || || '''''Results...''''' || ...of the above technique | + | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique |
|- | |- | ||
− | || || '''''Example(s) of how...''''' || ...the template should not be invoked if the situation is an easy error to make. | + | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template should not be invoked if the situation is an easy error to make. |
|- | |- | ||
− | || || '''''Results...''''' || ...of the above technique | + | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique |
|} | |} | ||
Revision as of 15:32, 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 | |||
.
Pages: Templates-List: General Use Only, Infobox-Related, Categories-Related, Sets of Related Pages, Doc. |
Contents
- 1 Template Documentation
- 2 Templates List
- 3 What to Consider When Creating or Documenting a Template
- 4 How to Document a Short Simple Template
- 5 How to Document a Template using a "/doc" Sub-Page
- 6 Documentation Sub-page for Template:(template_name)
- 6.1 Scope of Use
- 6.2 Paramaters
- 6.3 Examples
- 6.3.1 How to invoke this template for ...(idea 1)
- 6.3.2 How to invoke this template for ...(idea 2)
- 6.3.3 How to invoke this template for ...(idea 3)
- 6.3.4 How to invoke this template for ...(idea 4)
- 6.3.5 How to invoke this template for ...(idea 5)
- 6.3.6 How to avoid common error(s) while invoking this template for ...(idea 6)
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 | 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 relates to a Trunked Radio System | |
MultiState | the template relates to a TRS 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, 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:
Attribute | Details | |
---|---|---|
Template's Name | (case sensitive) | |
Template's Type |
| |
Template's Purpose | give a clear but concise explanation | |
What is expected to invoke this template? |
| |
What should not invoke this template? |
| |
Template's Parameters | if any are used | |
Parameter Name | (case-sensitive) | |
Parameter Description | if Parameter Name is unclear, because it is anonymous, numbered, or specified but abbreviated | |
Expected Value(s) |
this includes:
| |
Default Value | if default value feature is used | |
Is a parameter-value Required? | ||
Additional Notes about the parameter |
| |
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 | |
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 | |
Example(s) of how... | ...the template is invoked with the most complex or complete use of parameters. | |
Results... | ...of the above technique | |
Example(s) of how... | ...the template can be invoked to produce unexpected but useful results | |
Results... | ...of the above technique | |
Example(s) of how... | ...the template should not be invoked if the situation is an easy error to make. | |
Results... | ...of the above 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):
- Example:Template:Forum
...(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):
- Example: Template:Cat_State/doc
- Other "/doc" pages listed in Category:Documentation can be used as examples for specific types of templates.
- Templates themselves usually will not be assigned the "Category:Documentation" category.
- Templates' "/doc" sub-pages should be assigned the "Category:Documentation" category.
...(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) |
|
|
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. |