User:SWinxy/Internal Manual of Style

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

Templates
Templates should have the following syntax:

The template source code must reside in the place of, with no whitespace or line break preceding the end of the template and the opening   tag. A whitespace or line break is an error. 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. 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).

For small templates with not high use, it makes more sense to include the documentation right in the template itself. 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
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'.

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

Order
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.
 * 1) Hatnotes
 * 2) Documentation subpage (if a /doc subpage)
 * Documentation header templates
 * 1) Template redirects and template shortcuts
 * 2) Transwiki guide
 * 3) Lua
 * 4) Uses TemplateStyles
 * 5) Wikidata templates (Uses Wikidata, Tracks Wikidata, Wikidata property, or Tracks and uses Wikidata)
 * 6) Description of the template usage
 * 7) Usage
 * 8) Parameters
 * 9) TemplateData
 * 10) Tracking categories
 * 11) See also
 * 12) Navboxes
 * 13) Categories

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, 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, uses the Lua module Module:Message box, and places it off to the side.

Templatedata
Templatedata is always a good idea to include for VisualEditor. Collapsing or using a wrapper template is discouraged.

Tracking categories
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.

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

MOS pages
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.

Essays
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
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
 * (upsilon, displays as "Υ") for user templates
 * (omega, displays as "Ω") is for WikiProjects