Help:Documenting templates and modules
Templates and modules are very powerful features of MediaWiki, but can be confusing to new users and even experienced users can have difficulty making sense of the more complex ones. They should therefore be accompanied by documentation to improve usability.
Documentation should explain what a template or module does and how to use it. For templates in particular, it should be simple enough that a user without complete knowledge of the intricacies of template syntax – which includes many experienced contributors who focus their attention elsewhere – can use it correctly. This is especially true in the case of very widely-used templates.
What to include
[edit]Documentation should cover:
- Categories and InterWikimedia links, where applicable. These must be within a
<includeonly>…</includeonly>container. Modules cannot be categorised except through a documentation page, so this is particularly important for them. Every module should have a documentation page with a category, even if you don't write any other documentation (yet). Many categories are available, see Category:Templates and Category:Modules to browse through them. - The basic purpose of the template or module: what it does and if it is not immediately obvious, why it needs to be done. If there are other templates or modules with similar names or purposes, it's a good idea to mention those, in order to reduce the chance of the wrong one being used.
How to create a documentation subpage
[edit]Documentation subpages should be named and formatted using the following general pattern, for consistency.
{{documentation subpage}}
<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->
== Usage ==
<includeonly><!-- CATEGORIES AND INTERWIKIS HERE, THANKS -->
</includeonly>
The top line will display a message explaining the current page and a link to the template or module's main page. Insert the documentation after the top line and categories and interwikis under the appropriate comment line – leaving the comment in place, so that the layout is preserved when the page is edited in future. Then save the subpage.
Additional information for templates
[edit]In the case of a template, you will also need to add the documentation subpage to the template itself. Return to the template's main page, Template:X, in this example. Edit the template and append the following at the end of the template code:
[--last line of your template code--]<noinclude>{{documentation}}</noinclude>