Help:為模板和模組撰寫說明文檔

模板和模組是 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.