User:ArielGlenn/Template docu

Current practice
On enwikt there are two main methods of documenting a template:


 * 1) Use of  tags, and
 * 2) Putting documentation on the talk page.

Both of these have advantages and disadvantages. See Wiktionary talk:Template documentation which has a summary of discussions about these two alternatives. Another exposition lives at Meta:Help:Template documentation. As a refresher, you may want to visit Wikipedia:Transclusion costs and benefits.

One drawback not mentioned to having the template documentation on its talk page is that the talk page then contains both documentation and discussion about the template parameters or functionality or any other kind of random thing. In an ideal world we would have these two types of content separated.

In the meantime, in February 2007, a new method was proposed, that of transclusion of material on a separate page  under the template namespace. This permits locking of the template, separation of documentation from discussion, separate editing of documentation pages only, and reduced load on the servers as compared with the  method.

The idea for this originated at Wikipedia. See the history page at Wikipedia:Template doc page pattern. The new system is seeing use already; some 100 templates are currently using the transclusion method.

I think we ought to consider adopting this method for use here. I'm have converted the Greek conjugation templates to use it, as a testbed.

How to do it: Setting up a new doc page for a template
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:



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

How to do it: adding the right markup to the template page itself
In the page for template X, append after the template code:



Attention: Make sure the opening &lt;noinclude> 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.

Also, ensure that the categories added are similar to:

and not simply:

The name of the template needs to be identified in the category, otherwise the name of the documentation page will appear in the category.

Alternative method using Interwiki doc page pattern
NOTE: This method is not working yet!!

If you don't want to follow the two above steps, you can use the Interwiki doc page pattern template instead. I don't like it as well. YMMV.

First, create the /doc page under your existing template, with the following contents in it: and save the page.

Second, open up the /doc page for edit again. You will see a bunch of source in there, having been  for you. Follow the instructions: e.g. it will say, so do that. Then change the four include/noinclude tags to take out the space, e.g.  should be changed to. Add in Interwiki links in the area indicated (or remove the Interwiki-grp template call). Add in any category references in the area indicated. And add in the actual documentation about the template in the area indicated. Then save the page.

Add a call to the new /doc page on your template page, in  tags.

Now, tweak til you like it. For more details, see the Template:Interwiki doc page pattern.

Final notes
If (for example) you use the Interwikitmp-grp template on your template page, to show which sister projects use a similar template, this is a great thing to move to the new /doc page, since updates to it might be made frequenetly, and this way, the eits will create very little work for the server, as compared to being made on the template page itself.

You should also put categories (other then Category:Template documentation, which is done for you automatically) on the /doc subpage, in  tags.

Relevant Links
See the following pages:


 * Category:Template documentation
 * Template:Template doc page transcluded
 * Template:Template doc page viewed directly
 * Template:Template doc page transcluded/doc
 * Interwiki doc page pattern
 * Wikipedia:Template doc page pattern
 * Meta:Template doc page pattern