User:ArielGlenn/Template docu
|
This is an essay. It is not a policy or guideline; it merely reflects the opinions of some of its author(s). Please update the page as needed, or discuss it on the talk page. |
Current practice[edit]
On enwikt there are two main methods of documenting a template:
- Use of
<noinclude>tags, and - 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 /doc 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.
New method[edit]
How to do it: Setting up a new doc page for a template[edit]
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:
<includeonly>{{Template doc page transcluded}}</includeonly><noinclude>{{Template doc page viewed directly}}</noinclude>
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
<includeonly>
<!-- ADD CATEGORIES BELOW THIS LINE -->
<!-- ADD INTERWIKIS BELOW THIS LINE -->
</includeonly>
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[edit]
In the page for template X, append after the template code:
[--template code--]<noinclude>
{{{{FULLPAGENAME}}/doc}}
<!-- Add cats and interwikis to the /doc subpage, not here! -->
</noinclude>
Attention: 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, 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:
[[Category:Name|{{PAGENAME}}]]
and not simply:
[[Category:Name]]
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[edit]
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:
{{subst:Interwiki doc page pattern}}
and save the page.
Second, open up the /doc page for edit again. You will see a bunch of source in there, having been subst for you. Follow the instructions: e.g. it will say ----- Delete from this COMMENT line up TO TOP ----- , so do that. Then change the four include/noinclude tags to take out the space, e.g. <in cludeonly> should be changed to <includeonly>. 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 <noinclude> tags.
Now, tweak til you like it. For more details, see the Template:Interwiki doc page pattern.
Final notes[edit]
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 <includeonly tags.
Relevant Links[edit]
See the following pages: