User:SWinxy/Internal Manual of Style
 | The following is a draft working towards a proposal for adoption as a Wikipedia policy, guideline, or process. The proposal must not be taken to represent consensus, but is still in development and under discussion, and has not yet reached the process of gathering consensus for adoption. Thus references or links to this page should not describe it as policy, guideline, nor yet even as a proposal. |
 | This idea is in the brainstorming stage. Feel free to add new ideas; improve, clarify and classify the ideas already here; and discuss the merits of these ideas on the talk page. |
Navigating Wikipedia's internal system of essays, templates, manual of style pages, and policies is an overwhelming task to even regular editors. This page sets out to describe standards for how these 'internal pages' should be laid out in a consistent manner.
Links
[edit]Do not mix namespace aliases with shortcuts when the destination is visible. WP:Assume good faith and Wikipedia:AGF is incorrect. The resulting text or wikitext should always be consistent with the namespace. Wikipedia:Assume good faith and WP:AGF are proper links. When writing the link in full, the link should be the final destination page (e.g. Wikipedia:Documentation is incorrect, as it redirects to Wikipedia:Template documentation). The full destination page is preferred in hatnotes, but when linking to sections with long names, the result may be too long to be comfortable, and a shortcut is allowable.[a]
Templates
[edit]Templates should have the following syntax:
<actual template><noinclude>
{{Documentation}}
</noinclude>
The template source code must reside in the place of <actual template>, with no whitespace or line break preceding the end of the template and the opening <noinclude> tag. A whitespace or line break is an error.[b] Template code should be careful to not have line breaks in the source, as that would insert line breaks into the result, unless otherwise intended. For clarity and readability, HTML comments can be used to create whitespace that a normal programming language would ignore. {{Documentation}} is wrapped in a pair of tags which automatically transcludes the /doc subpage (if there is no subpage, there will be links to create one).[c]
For small templates with not high use,[d] it makes more sense to include the documentation right in the template itself. {{Documentation|content=<documentation>}} can be used for that.
Templates like message boxes should be able to render the final result when viewing its template page. For instance {{cleanup}} shows how the final result will appear if used plain. While it's better to do it, it can be challenging for large templates or ones with many parameters, or ones that change depending on the page type.
Naming convention
[edit]Template names should be consistent with similar templates. Navbars should have the subject of their topic as their title. Alternatively, the title should have the word 'navbar' at the end. Sidebars should always have the subject name and then the word 'sidebar'.
| Type | Format | Example |
|---|---|---|
| Navbar | {{<subject>}} | {{Earth}} |
| Sidebar | {{<subject> sidebar}} | {{Geography sidebar}} |
| Infobox | {{Infobox <subject>}} | {{Infobox planet}} |
| WikiProject banner | {{WikiProject <subject>}} | {{WikiProject Solar System}} |
| Citation | {{Cite <medium>}} | {{Cite tweet}} |
Subpages
[edit]
Notably what is absent is the presence of categories, actual documentation, and TemplateData. Those things are separated into a subpage. High-use templates are protected so that only Template Editors can edit. Documentation doesn't affect the resulting template transclusion (when noinclude'd properly), so documentation pages are a way for any editor to edit the documentation when they don't need to edit the template.
The /sandbox and /testcases subpages are commonly used to test changes to the template before going live. Moderately-used templates may want to have tests performed on them before being copied over to the live template to make sure nothing horribly breaks. Showing you do tests for template-protected templates is also a criteria for the Template Editor right.
Template documentation
[edit]The documentation, typically on the /doc subpage, for a template should: 1) indicate what the template does; 2) describe its functionality; and 3) link to related policies, guidelines, essays, and other templates.
| Template | Explanation |
|---|---|
{{subst:doc-code}}
|
Substitutes a blank template with {{Documentation}} |
{{Markup}}
|
Creates a side-by-side markup comparison |
{{Markup2}}
|
Shows a bold title, markup, and the resulting output. |
{{Demo}}
|
Shows a template wikicode alongside the invocation of the template |
{{Never substitute}}
|
Indicates the template should not be substituted with {{subst:}}
|
{{Always substitute}}
|
Indicates the template should always be substituted with {{subst:}}
|
{{Parameter names example}}
|
Creates an example usage of the template, passing values to the template surrounded by three brackets. |
Order
[edit]- Hatnotes
- {{Documentation subpage}} (if a /doc subpage)
- Documentation header templates
- {{Template redirect}}s and {{template shortcut}}s
- {{Transwiki guide}}
- {{Lua}}
- {{Uses TemplateStyles}}
- Wikidata templates ({{Uses Wikidata}}, {{Tracks Wikidata}}, {{Wikidata property}}, or {{Tracks and uses Wikidata}})
- Description of the template usage
- Usage
- Parameters
- TemplateData
- Tracking categories
- See also
- Navboxes
- Categories
Hatnotes are a great way to, like in mainspace pages, direct the editor to the appropriate template. See also, redirects here, etc. should be used if there's a possibility an editor ends up in the wrong place.
Template shortcuts and redirects are similar to Wikipedia shortcuts, in that they display a floating box to the right to show the most commonly-used aliases to arrive at the page. When a template is primarily there to invoke a module or makes heavy use of one or many modules, {{lua}} places a floating box to indicate the usage of them. It is not necessary to list every single module that may get used. For example, {{mbox}} uses the Lua module Module:Message box, and places it off to the side.
Documentation content
[edit]Using a glossary
[edit]Using tables
[edit]Templatedata
[edit]Templatedata is always a good idea to include for VisualEditor. Collapsing or using a wrapper template is discouraged.
== TemplateData ==
{{TemplateData header}}
<templatedata>
...
</templatedata>
Tracking categories
[edit]Templates that add categories for tracking usage and errors should list them with {{clc}} in a dedicated section and add the template to Category:Templates that add tracking categories.
== Tracking categories ==
* {{clc|Tracking category}}
Categories
[edit]Categories should be added to the template, as applicable, which may be found in Category:Wikipedia templates. Placing a category in the documentation subpage would add the template's documentation page to these categories, so it must be wrapped in an includeonly tag.
<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Some category]]
}}</includeonly>
MOS pages
[edit]Conveying the standard ways of Wikipedia's writing requires a standard of itself to dictate it. The Manual of Style should clearly convey the right and wrong thing to do, a rationale or reasoning for doing so, and pointers to related topics.
The templates {{xt}} and {{!xt}} give clear indications on the correct usage and the incorrect usage of something ('xt' denoting 'example text' and '!xt' being the inverse in computer science). Place them where an easy remedy is possible to convey.
| Template | Explanation | Example | Renders as |
|---|---|---|---|
{{tl}}
|
Creates a link to a template surrounded by double curly brackets ({{}}) | {{tl|tq}}
|
{{tq}} |
{{tlx}}
|
Same as {{tl}}, but wrapped in <code></code> tags | {{tlx|tq}}
|
{{tq}}
|
{{tlxs}}
|
Same as {{tlx}}, but includes subst: | {{tlxs|tq}}
|
{{subst:tq}}
|
Policies
[edit]Essays
[edit]Using photos to illustrate a point is a useful tool. Photos and their captions are also ways for humor to be added in subtle ways where humor is generally not allowed.
Categories
[edit]Cleanup categories should have clear and instructions on how to empty the category.
The usage of Greek letters for sort keys is particularly useful for guiding readers to important pages:
Σ(capital sigma) is used to place stub categories at the end of subcategory lists (µ(mu) was previously used, but the capital version "Μ" was confusing)β(beta, displays as capital, "Β") is for barnstarsΔ(delta) is for documentation, where sorting by Latin D is undesirableι(iota, displays as "Ι") is for Wikipedia imagesρ(rho, displays as "Ρ") is for portalsτ(tau, displays as "Τ") is for templates. Keep in mind, template categories should not be added to content categories per WP:CAT#Tυ(upsilon, displays as "Υ") for user templatesω(omega, displays as "Ω") is for WikiProjects
See also
[edit]Notes
[edit]- ^ At what point the length matters is up to the editor and common sense should be employed.
- ^ It may be required for technical reasons to include a line break, but is often a mistake.
- ^ Template:My special template will have its documentation page automatically be Template:My special template/doc. This can be overridden, for example for when many templates have identical syntax but different page names, to point to a single documentation subpage for all of them.
- ^ Reducing the amount of pages shrinks the amount of counter-vandalism work that needs to be done, and reduces the amount of pages one needs to watch. For a small template following the subpage structure, two or even three pages need to be watched for vandalism. That's okay for larger templates with more eyes on them, but it's not the same for smaller templates. 'Small' templates are ones that have simple wikitext, don't invoke modules directly, only used in a handful of pages (<10), and wouldn't forsee any need for page protection.