帮助:为模板和模组撰写说明文档

模板和模组是 MediaWiki 的强大功能，但对新手而言，可能不易上手，即使对在行人而言，较为复杂的代码仍可能会令人困惑。因此，应为其配上说明文档，以便功能为人使用。

说明文档应交代模板或模组的用途及使用方法。单就模板而言，说明文档应十分简洁，要让使用者在不完全了解复杂模板语法的情况下，仍能正确使用；同时也方便在行人去注意其他细节。大范围使用的模板尤要如此。

要写什么

说明文档应涵盖：

所属分类：当功能可以归为某一分类时，请将其加入说明文档，且务必置于 <includeonly>…</includeonly> 中。尤其要注意，模组只能透过说明文档页新增分类，所以请务必在模组文档中写入分类。即使说明文档尚未写任何内容，也一定要为所有模组建立说明文档页，并加入分类。可供选择的分类众多，详见“分类:模板”和“分类:模组”。
模板或模组的基本用途：交代功能效果，若功能的效果并非显而易见，请交代使用此功能的原因。若其他模板或模组有相似的名称或用途，也最好写出来，以免用错。
模板或模组的参数：不论是序号、名称或是选填参数，都要写出其预设值及作用。务必明确交代参数值的范围或限制，如“填 "yes", "no" 或数字”。
模板的用法范例：明确交代应该使用什么 Wikitext 及其呈现的效果。可以将 wikitext 置于 <code>…</code> 中，這樣就能做到清晰呈現且便於複製。如果模板有多种使用方式，例如，填写选填参数或不填写选填参数，请提供所有情况的范例。建议直接将模板嵌入到说明文件中，将每种填写参数的方式都列举出来，这样就可以呈现模板实际的效果。
相关模板或模组：若模板或模组与其他功能拥有共同的用途，请列出这些功能的连结。尤其要注意，每个相关的功能彼此之间都要有相互的连结，以方便浏览。

说明文档要存放在模板或模组的子页面中，以 /doc 命名。模组会自动将 doc 子页面嵌入至主页面。模板无法自动嵌入文档，所以请务必使用 {{documentation}} 模板来嵌入子页面。将文档存放在子页面中可使得说明文档与复杂的模板代码分开，让编辑文档更方便。It also allows templates to be protected where necessary, while allowing anyone to edit the documentation and categories. Text on the template page itself adds to the amount of text which must be processed when displaying the template, which is limited for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason).

How to create a documentation subpage

Documentation subpages should be named and formatted using the following general pattern, for consistency.

Suppose your template is named Template:X, or your module is named Module:X. Create a subpage with the name Template:X/documentation or Module:X/documentation. See the details at {{documentation subpage}} or copy-paste the following wikitext as a start for your documentation:

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

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>

This will transclude {{documentation}} at the bottom of the template page.

Important: Make sure the opening <noinclude> begins on the same line as the last character of the template code or text, and not on a new line. Otherwise, extra space will be inserted below the template when it is used, which is usually not wanted.

If the template is already protected, ask an administrator to do this or request an edit on the template's talk page. If documentation, categories and interwiki links already exist in a section, enclosed within a <noinclude>…</noinclude> container, move them into the documentation subpage, as it is best not to have documentation split across two separate pages.

Note that if the {{documentation}} template is put on the template page first, one can benefit from the preload feature to get a pre-filled doc page skeleton; if the documentation page does not exist yet, clicking the edit link on the template page will preload the contents of Template:documentation/preload into the editbox of the /documentation subpage.

Categories and interwiki links

To place the template or module itself into a category, add the [[Category:Category name]] code inside an <includeonly>...</includeonly> section on the documentation subpage.

To create an interwiki link for the template or module itself, add the [[Languagecode:Template name]] code inside an <includeonly>...</includeonly> section on the documentation subpage.

To place the documentation subpage into a category, add the [[Category:Category name]] code inside a <noinclude>...</noinclude> section on the documentation subpage.

To make the template place an article into a category (when the article includes the template), add the [[Category:Category name]] code inside an <includeonly>...</includeonly> section on the template page. For modules, the equivalent is to "return" the category's code as part of the returned wikitext.

Example

See the heavily-used Template:en-noun for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Template:en-noun/documentation is unprotected and can still be edited.

Several templates, one documentation page

When several templates work together or are very similar, then it is often clearer and easier to maintain one single documentation page that documents them together. The simplest way to do this is to make a full documentation page at one of the templates, and then make "redirects" from the other templates' documentation pages. See Template:nl-conj-wk and Template:nl-conj-st for an example of this principle.