Template documentation

This page describes how to write, structure, and maintain documentation for templates on Wikipedia. Clear documentation helps editors understand a template’s purpose, parameters, usage, limitations, and maintenance needs.

Scope

Applies to all templates, including infoboxes, navboxes, message boxes, citation templates, and utility templates.
Covers documentation placement, parameter definitions, examples, categories, tracking and maintenance, and common pitfalls.
For Lua modules, see Wikipedia:Lua and Wikipedia:Module documentation.

Where documentation goes

Use the {{Documentation}} system:

 * Create a subpage at Template:Name/doc.
 * Transclude it in the main template with {{Documentation}} below the template code.

Avoid placing long documentation directly in the template page; it complicates editing and increases server load.
For shared templates imported from MediaWiki or other projects, document local usage and differences on the /doc subpage.

Basic structure of a /doc page

Suggested sections:

Lead: one-sentence summary of the template’s purpose and scope.
Usage: how and where to use the template.
Parameters: full list with descriptions, types, defaults, and examples.
Examples: copy-pasteable usage examples and corresponding output.
Notes: edge cases, limitations, and known issues.
Maintenance: tracking categories, subpages, and talk page guidance.
See also: related templates, tools, policies, and help pages.
Categories: put maintenance and topical categories at the bottom.

Parameters

Document each parameter explicitly:

Name: the parameter name as used in wikitext.
Type: text, number, date, page title, file name, yes/no, list, etc.
Required?: whether the template fails or degrades without it.
Default: value if the parameter is omitted.
Aliases: any alternative parameter names.
Auto-formatting: if the template normalizes capitalization, spacing, or units.
Constraints: allowed values, ranges, and invalid inputs.
Interaction: how parameters interact or override each other.

Example parameter table (simplified):

Parameter	Required	Type	Default	Description
`title`	yes	text	—	The visible title displayed in the box.
`date`	no	date (ISO)	current	Rendered in localized format.
`link`	no	page title	—	Target page for the title; if omitted, title is plain text.

Examples

Provide minimal and full examples:

{{ExampleTemplate
|title=Sample
|date=2025-11-30
|link=Sample page
}}

Rendered output: explain what users should expect, including conditionals when parameters are missing.

Categorization

Place usage categories on articles (via the template output), not on the /doc page.
Place maintenance categories on the /doc page (hidden if necessary), e.g.:

 [[Category:Template documentation pages]]

Use hidden categories for tracking (e.g., pages with deprecated parameters).

Tracking and maintenance

Consider adding tracking categories from the template when parameters are deprecated or misused.
Use Special:WhatLinksHere to audit usage.
Use to locate transclusions.
Document any deprecations and migration paths in the /doc page.

Internationalization

If the template supports multiple languages or scripts, document the behavior and fallback rules.
Avoid hardcoding language-specific output unless intended; document how to switch locales.

Accessibility

Document ARIA roles, headings, and contrast requirements if the template produces UI elements.
Ensure semantic HTML in output. Avoid tables for layout unless necessary.

Performance

Minimize expensive parser functions and deep recursion.
Document known performance constraints, especially in heavily transcluded templates (infoboxes, navboxes).

Lua and Scribunto

For Lua-backed templates, describe the module entry points, exposed functions, and parameter mapping.
Link to the module at Module:Name and document any templates that wrap the module.

Common pitfalls

Undocumented required parameters.
Silent failures or ambiguous defaults.
Overly clever logic without explanation.
Using categories incorrectly (polluting article spaces).
Copying external documentation without adapting to local conventions.

Template/doc page template

You can copy and adapt the following skeleton for a /doc subpage:

{{Documentation header}}

'''Template purpose''': Brief description of what this template does and where to use it.

== Usage ==
{{Tnavbar|Template:Name}}
Place this template on pages that … Provide a one-line usage summary.

== Parameters ==
;title: required — visible title
;date: optional — ISO date, defaults to current
;link: optional — page title to link the title

== Examples ==
Minimal:
{{Template:Name
 |title=Example
}}
Full:
{{Template:Name
 |title=Example
 |date=2025-11-30
 |link=Example page
}}

== Notes ==
* Edge cases, limitations, and fallback behavior.

== Maintenance ==
* Tracking categories: [[Category:Example tracking category]]
* Deprecated parameters: document migration path.
* See also the talk page for open issues.

== See also ==
* [[Help:Templates]]
* [[Wikipedia:Template namespace]]
* [[Wikipedia:Lua]]
* [[Wikipedia:Module documentation]]
* Related templates: {{tl|Tnavbar}}, {{tl|Documentation}}

[[Category:Template documentation pages]]