Help:Template doc page pattern - Revision history

OmniMediaGroup at 19:58, 27 December 2007

2007-12-27T19:58:52Z

OmniMediaGroup: Centiare:Template doc page pattern moved to Help:Template doc page pattern

2007-12-27T19:56:57Z

Centiare:Template doc page pattern moved to Help:Template doc page pattern

Centiare at 16:50, 7 December 2006

2006-12-07T16:50:46Z

New page

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? ==
Centiare editors generally like to have a usage description of the template right at the template page (example: [[template:cite news]]). This can be achieved by writing some descriptive text into the template wiki-source inside <nowiki><noinclude>...</noinclude></nowiki>. However, this has some drawbacks:

* The text inside <nowiki><noinclude>...</noinclude></nowiki> does add to the ''pre-expand include size'', which is limited (see [[Centiare:Template limits]]).
* Some templates are fully protected, because they are transcluded into a lot of 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, the more a template is included, it's pre-expanded size gets multiplied by however many bytes its size needs. So there are conflicting needs. (see [[Centiare:Template limits]]).

This ''How to'' page sets forth a strategy'' 'and technique' ''that satisfies both the human 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 sum, 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 {{I}}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. {{I}}2. - Key protected templates that are fully matured can be edited for documentation adds, clarity, categories, et. al. without bothering the main utility.

== How-to do it ==
For a template with the name Template:X, create a subpage with the name Template:X/doc and copy/paste the following wikicode for a start into that page:

:<code style="display:table; line-height:1.2em;"><nowiki>
<includeonly>{{template doc page transcluded}}</includeonly><noinclude>{{template doc page viewed directly}}</noinclude></nowiki> <nowiki>
</nowiki> <nowiki>
</nowiki> <nowiki>
<includeonly></nowiki> <nowiki>
</nowiki> <nowiki>
</nowiki> <nowiki>
</nowiki> <nowiki>
</includeonly></nowiki> <nowiki>
</nowiki></code>

Insert the documentation, categories and interwikis as indicated by the respective comment lines (see above).

In the page for template X, append:

:<code style="display:table; line-height:1.2em;"><nowiki>
<noinclude>{{{{FULLPAGENAME}}/doc}}</nowiki> <nowiki>
</nowiki> <nowiki>
</noinclude></nowiki> <nowiki>
</nowiki></code>

'''Attention''': Make sure the opening <nowiki><noinclude></nowiki> begins on the same line as the last character of the template code (or text), not on a new line. Otherwise, an additional newline will be inserted into pages transcluding X (which is almost never wanted).

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.

== Benefits ==
* Edits to the X/doc page only propagate 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 [[m:Help:job queue|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 ==
* Tim Starling 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."'' [http://en.wikipedia.org/w/index.php?title=Wikipedia:Village_pump_%28technical%29&diff=prev&oldid=69888944]

== Examples ==
* [[template:cite web]] (protected), [[template:cite web/doc]] (unprotected)

== See also ==
* [[m:Help:Templates#Noinclude_and_includeonly|<noinclude> and <includeonly>]]
* [[Centiare:High-risk templates]]
* [[Template:template doc page transcluded]]
* [[Template:template doc page viewed directly]]

[[Category:Centiare templates|{{PAGENAME}}]]
[[Category:Centiare how-to|{{PAGENAME}}]]

@@ Line 2: / Line 2: @@
 == What does it solve? ==
-Centiare editors generally like to have a usage description of the template right at the template page (example: [[template:cite news]]). This can be achieved by writing some descriptive text into the template wiki-source inside <nowiki>&lt;noinclude>...&lt;/noinclude></nowiki>. However, this has some drawbacks:
+MyWikiBiz editors generally like to have a usage description of the template right at the template page (example: [[template:cite news]]). This can be achieved by writing some descriptive text into the template wiki-source inside <nowiki>&lt;noinclude>...&lt;/noinclude></nowiki>. However, this has some drawbacks:
-* The text inside  <nowiki>&lt;noinclude>...&lt;/noinclude></nowiki> does add to the ''pre-expand include size'', which is limited (see [[Centiare:Template limits]]).
+* The text inside  <nowiki>&lt;noinclude>...&lt;/noinclude></nowiki> does add to the ''pre-expand include size'', which is limited (see [[Help:Template limits]]).
 * Some templates are fully protected, because they are transcluded into a lot of 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, the more a template is included, it's pre-expanded size gets multiplied by however many bytes its size needs. So there are conflicting needs. (see [[Centiare:Template limits]]).
+* There is an upper limit to both the pre-included and post-expanded sizes of a page. Worse, the more a template is included, it's pre-expanded size gets multiplied by however many bytes its size needs. So there are conflicting needs. (see [[Help:Template limits]]).
 This ''How to'' page sets forth a strategy'' 'and technique' ''that satisfies both the human 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!)
@@ Line 55: / Line 55: @@
 == See also ==
 * [[m:Help:Templates#Noinclude_and_includeonly|&lt;noinclude> and &lt;includeonly>]]
-* [[Centiare:High-risk templates]]
+* [[Help:High-risk templates]]
 * [[Template:template doc page transcluded]]
 * [[Template:template doc page viewed directly]]
-[[Category:Centiare templates|{{PAGENAME}}]]
+[[Category:MyWikiBiz templates|{{PAGENAME}}]]
-[[Category:Centiare how-to|{{PAGENAME}}]]
+[[Category:MyWikiBiz how-to|{{PAGENAME}}]]

← Older revision	Revision as of 19:56, 27 December 2007
(No difference)