The template doc page pattern is a method to securely split template documentation off from template code in a separate page. It enables full protection of template code while retaining the documentation part unprotected, so that everyone can still edit the documentation.

What does it solve? Edit

Wikipedians and Wikians who use templates generally like to have a usage description of the template right at the template page (example: Wikipedia:template:cite news). This can be achieved by writing some descriptive text into the template wiki-source inside <noinclude>...</noinclude>. However, this has some drawbacks:

  • The text inside <noinclude>...</noinclude> adds to the pre-expand include size, which is limited (see Wikipedia:Wikipedia:Template limits).
  • Some templates are fully protected, because they are transcluded into many pages. Editing the documentation is awkward in this case, because non-sysops must make a request to edit a protected page and a sysop has to do the edit.
  • There is an upper limit to both the pre-included and post-expanded sizes of a page. Worse, if a template is included more than once, its pre-expanded size gets multiplied by however many bytes its size needs. So there are conflicting needs. (see Wikipedia:Wikipedia:Template limits).

This How to page sets forth a strategy 'and technique' that both satisfies people's needs to refresh their memory (or most commonly, learn from the first exposure! The 'needs' for documentation, especially for the newer editors still on the many steep wiki learning curves.) and has the added benefit of building pages faster and unloading the servers' processing loads. (We all do love to wait for that page to load, soooo much!)

In summation, the dual solution is to place the documentation and usage notes in a documentation template instead of the tool or utility template (which, if worded carefully, can usually cover several related tools or utility type templates) that is walled behind a <noinclude>...</noinclude> block that is very short... so easy on the processor and, thus, we get to have our documentation cake and eat it too –  faster!

The solution also has two apppreciable spin-off benefits:

  1. It minimizes server loading again for widely used templates, which occurs when they are updated in the least way, such as when someone adds a foreign language interwiki link.
  2. Key protected templates that are fully matured can be edited for documentation adds, clarity, categories, etc. without bothering the main utility.

How to do it Edit

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

(If the template exists and is already protected, ask an administrator to do this, or request an edit by using {{editprotected}} on the template's talk page.)

Now see, which is derived from the relatively new Wikia standard. Some of it is reproduced and expanded below, but it can probably be used without further reference to this page.

Link template to new subpageEdit

Briefly, add this to the template:

<includeonly>Any categories to be inserted into articles by the 
template</includeonly><noinclude> {{documentation}} </noinclude>

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

The "categories to be inserted into articles by the template" may already be elsewhere on the page; move them into the above block, for consistency.

Save the page. A gray box will appear, containing, among other things, a link to the "/doc" subpage.

Create subpageEdit

Suppose your template is named Template:X. You will be creating a subpage with the name Template:X/doc. Click on the link that appeared when you saved the template; use the following wikitext as a start for the documentation:

(Optionally this template:) {{Documentation subpage}}
:This template is used to do something.
:Type <code>{{t|templatename}}</code> somewhere.
;Sample output
:<code><nowiki>{{templatename|foo}}</nowiki></code> gives...

<includeonly>Any categories for the template itself
[[Category:Template documentation|{{PAGENAME}}]] </noinclude>

Use any or all of the above description/syntax/sample output sections, preferably in the same order. You may also want to add "see also" or further usage information sections.


If documentation, categories, and interwiki links already exist in a section enclosed with <noinclude> tags, move them into the documentation subpage, as it is best not to have documentation split across two separate pages.

The template itself can now be fully protected, while its documentation page at 'X/doc' can remain fully unprotected so that everyone can edit the documentation. However, note that cascade-protecting the template also protects the doc page.

Benefits Edit

  • Edits to the X/doc page propagate only to the template display page itself, not to transclusions of X. Pages transcluding X are therefore not dependent on the doc page, so edits to the doc page don't inflate the job queue for heavy use templates.
  • Edits to the documentation can't do any harm to the template itself and to transcluding pages. Vandalism to the doc page doesn't propagate into pages transcluding X.
  • Everyone can edit the template documentation, even if the template itself is fully protected. Categories and interwikis can be easily added to the X/doc subpage.

References Edit

  • Tim Starling (now married to User:Angela) wrote: "If the documentation is large or frequently changed, I'd recommend that you move it to a subpage. Then you can transclude it into both the <noinclude> section and the talk page." [1]

Wikipedia has since moved to make the subpage procedure standard.

Examples Edit

See also Edit

External linksEdit

This page uses Creative Commons Licensed content from Wikipedia (view authors). Smallwikipedialogo