View source for Wikipedia talk:Template documentation/Archive 2

{{talkarchivenav}}

== Bot request ==
{{Resolved|1=Long since cleaned up.}}
I have made a request over at [[Wikipedia:Bot requests#Template documentation]] that all occurrences of "{{tlc|/doc}}" should be changed to "{{tlc|documentation}}" on template pages. I also asked that "{{tlc|template doc}}" and "{{tlc|documentation, template}}" should be changed to "{{tlc|documentation}}".

--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 18:14, 17 April 2008 (UTC)
:The bot wrangler [[User:Dycedarg|Dycedarg]] responded that there were only 157 templates using the code {{tlc|/doc}}, so instead he made a list of them so we can fix them by hand. (They probably need some other fixes too since they use that old method.) The list is available at [[Wikipedia:Template documentation/List]].
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 10:37, 18 April 2008 (UTC)

== Zoobox ==
{{Disregard|1=Off-topic; try [[WT:INFOBOX]].}}
I am working on a project for WikiProject Animals-- a second infobox, which will feature statistical data about each species.  Some of of think it would be beneficial, so I am taking the responsibility to provide a rough draft infobox.  Unfortunately, there are a few issues with it.  Could I get some help cleaning it up?  I used the Taxobox as a foundation and have basically removed and added code to that.  It is still rather messy and the graphic and audio aren't even appearing within the boundaries of the box like they should.  [[User:Bob the Wikipedian/Zoobox]]

Thanks in advance, [[User:Bob the Wikipedian|Bob the Wikipedian, the Tree of Life WikiDragon]] ([[User talk:Bob the Wikipedian|talk]]) 22:27, 30 April 2008 (UTC)

== Any standard for internal developer docs? ==
{{Resolved|1=Issue sorted itself out.}}
Is there is standard for documenting subtemplates not intended to be called alone... only used for subroutine-type purposes? Should these be on the main doc subpage, or should there be a separate subpaged named devdoc or such? Should they be documented in one place, even, or should each subtemplate have its own doc? &ndash;&nbsp;[[User:Flamurai|flamurai]]&nbsp;([[User talk:Flamurai|t]]) 17:48, 14 May 2008 (UTC)
:I assume you don't mean regular meta-templates that are used on many different templates, right? Instead you mean like there is a template {{tlf|Bigtemp}} that internally uses {{tlf|Bigtemp/header}} and {{tlf|Bigtemp/footer}}. And editors that use {{tlf|Bigtemp}} don't need to be aware of {{tlf|Bigtemp/header}} and {{tlf|Bigtemp/footer}}, right?
:The only such case that comes to my mind was the old navbox that used a navbox/core. And the technical documentation were at navbox/core. Navbox just mentioned the navbox/core in one sentence on the usage documentation with a link to it. So most editors didn't have to be confronted with the technical documentation.
:In the case where there are several subtemplates, like {{tlf|Bigtemp/header}} and {{tlf|Bigtemp/footer}} and so on, then I would do as I do in other cases where there are several templates that belong together, and what we already recommend at [[Wikipedia:Template documentation#Several templates, one documentation page]]: I would put the full technical documentation at one of the subtemplates, say {{tlf|Bigtemp/header/doc}} and then just put very short /doc pages at the others with links to the main documentation at that one subtemplate. So {{tlf|Bigtemp/footer/doc}} would say: "See full documentation at {{tlf|Bigtemp/header}}."
:I would ''not'' put the technical documentation in a special /devdoc page directly under the main template. Since that page needs to be shown somewhere, so I think it is better to show the documentation with one of the subtemplates. I have been programming computers since 1982 and I quickly learnt that maximum one documentation file per source code file is a good idea. I also learnt the hard way here at Wikipedia that several templates should not show the same /doc file. Since then people start to put lots of weird if-cases in them to handle interwikis and categorisation and to differentiate the text depending on where they are shown. So it is better to use "soft redirects" like I described above.
:Unfortunately the {{tlf|Documentation}} template does not automatically support this. It is currently "too smart" and instead of showing {{tlf|Bigtemp/header/doc}} on {{tlf|Bigtemp/header}} it shows {{tlf|Bigtemp/doc}} on {{tlf|Bigtemp/header}}. So in the noinclude area of {{tlf|Bigtemp/header}} one has to put this: {{tlf|Documentation|Template:Bigtemp/header/doc}}.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 19:12, 14 May 2008 (UTC)
:: All right. I think what I will do is just put short doc pages on each template as quasi-function documentation. Really all that's needed is to list the parameters. I just have condensed a mess of 24 subtemplates down into 2 at {{tl2|ribbon devices}}, and I don't want the next person who wants to modify the template to go through the trouble I went through figuring out what's going on. &ndash;&nbsp;[[User:Flamurai|flamurai]]&nbsp;([[User talk:Flamurai|t]]) 19:22, 14 May 2008 (UTC)

== Categories and documentation ==
{{Resolved|1=Question answered.}}
I apologize if this has been answered somewhere, but I haven't been able to track it down. Let's say in my documentation I decide to create an example to show how the template is used, I do this by enclosing one example in <nowiki><pre></pre></nowiki> tags and then running the exact same example without the tags (thus executing it). This all works just fine, however the template is encoded with category tags and then tags the template docs and page itself into those categories. Is there any way to prevent this? To make it so that it can execute this template once while somehow ignoring the category calls within it? Any help would be appreciated, thanks. [[Special:Contributions/75.68.115.240|75.68.115.240]] ([[User talk:75.68.115.240|talk]]) 22:42, 7 July 2008 (UTC)
:See [[m:Help:Category#Selective category inclusion]] (2nd part).--[[User:Patrick|Patrick]] ([[User talk:Patrick|talk]]) 22:47, 7 July 2008 (UTC)
::Works beautifully! What a unique method. Thanks! [[Special:Contributions/75.68.115.240|75.68.115.240]] ([[User talk:75.68.115.240|talk]]) 23:18, 7 July 2008 (UTC)

== 'Template Documentation' Headings ==
{{Resolved|1=Fixed.}}
Please see [[Template talk:Documentation#Heading fix]] for a discussion regarding the accessibility or otherwise of headers in {{tl|documentation}}. Thank you. [[User:Pigsonthewing|Andy Mabbett]] (User:Pigsonthewing); [[User talk:Pigsonthewing|Talk to Andy Mabbett]]; [[Special:Contributions/Pigsonthewing|Andy Mabbett's contributions]] 10:53, 8 September 2008 (UTC)
:Still unresolved. [[User:Pigsonthewing|Andy Mabbett]] (User:Pigsonthewing); [[User talk:Pigsonthewing|Andy's talk]]; [[Special:Contributions/Pigsonthewing|Andy's edits]] 23:28, 23 August 2009 (UTC)
::Fixed as of December 2011. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 01:17, 5 January 2012 (UTC)

== Categories and interwiki links ==
{{Resolved|1=Question answered.}}
Hey, the [[Wikipedia:Template_documentation#Categories_and_interwiki_links|Categories and interwiki links]] section says these should be placed on the /doc subpage ... why? Tks [[User:Ling.Nut|Ling.Nut]] <sup>([[User talk:Ling.Nut|talk]]&mdash;[[User:Ling.Nut/3IAR|WP:3IAR]])</sup> 08:56, 15 October 2008 (UTC)
:One of the main purposes of this documentation system is to separate the template code and the documentation from each other, so the template can be protected (if needed) but the documentation still can be edited by everyone. We also want that everyone should be able to help out to update the categories and the interwiki links, thus they should be placed in the &lt;includeonly> &lt;/includeonly> section on the /doc page. Consider that often interwiki links are updated by users from other language Wikipedias. That is users who doesn't even have an account on the English Wikipedia, so they can not even update a semi-protected template.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 12:27, 15 October 2008 (UTC)

== Stub templates ==
{{FYI|Documentation was updated.}}
Hi all - I've added a short section explaining the reasons why stub templates generally don't have documentation (basically because the link to [[WP:STUB]] in all stub templates serves the same purpose but has additional benefits). [[User:Grutness|Grutness]]...''[[User_talk:Grutness|<small style="color:#008822;">wha?</small>]]'' 00:34, 11 February 2009 (UTC)

== Shared documentation ==
{{Stale|1=No further progress in establishing a standard for this in over 2 years.}}
Is there a best practise where to place interwiki links and categories if a documentation page is shared? E.g., {{tl|Wikinewscat}} should share the documentation of {{tl|Wikinews}}, but has different interwiki links.<br>I was thinking about putting the categories and interwikis on seperate template subpages (for which I can't think of a good name) and transclude that one inside the <code>includeonly</code> area of the documentation page, using a relaibe path, so that it will transclude the matching interwiki/category subpage into each template.<br>Is there a better way to go about this? --[[User talk:Amalthea|<span style="font-family:Verdana;font-variant:small-caps;color:#823824;font-weight:normal">Amalthea</span>]] 11:44, 7 April 2009 (UTC)
:Having anything else than a plain /doc subpage with the interwikis wreaks havoc with the interwiki bots. And even human editors have big problems with adding the interwikis and categories at the right place if you use the same /doc page in several places. (Since then you need a lot of if-cases checking what page the /doc is on.) Adding the interwikis even further away as you suggest will create even more problems. And remember, not all Wikipedias even use /doc pages, so our /doc page system is already pretty confusing for editors from other language versions that come here to put interwikis on our templates.
:Instead there is a much simpler solution that we use in many templates:
:Create a /doc page for each template in a template group. Decide that one of them is the "main" template. Write the long documentation at the /doc page for the main template. Then only have short /doc pages for the "sister" templates that link to the main template, by stating "See full documentation at {{tl|main template}}." This means each template has its own /doc page where categories and interwikis can be put as usual.
:See for instance the main template {{tl|nowrap begin}}, with its helper templates {{tl|nowrap end}}, {{tl|·wrap}} and so on.
:Or the main template {{tl|shortcut}} with its sister templates {{tl|shortcut-l}} and {{tl|policy shortcut}}.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 15:58, 7 April 2009 (UTC)
:: Eh, interwiki bots ... didn't realize they are working in template space, too.<br>Hmm, having only a soft redirect documentation page works around those problems, but isn't quite as neat for template users. I'd typically put readers' usability far above editors' usabiility.<br>I'm guessing that you also wouldn't like transcluding the actual documentation in both /doc pages from a /doc2 subpage of one of the templates? :) That would keep the interwiki bots and foreign language interwikians happy, and only is a hassle for people wanting to edit the documentation.<br>[[User talk:Amalthea|<span style="font-family:Verdana;font-variant:small-caps;color:#823824;font-weight:normal">Amalthea</span>]] 16:09, 7 April 2009 (UTC)
:::I think the soft redirects make things ''less'' confusing for those who read the documentation. Since I find it annoying and confusing to read the documentation of several similar templates, only to discover after a while that I am rereading the same documentation. 
:::Or even worse, some template coders add if-cases in the documentation so it isn't exactly the same documentation, forcing you to actually read all the similar versions...
:::Soft redirects make it clear for the readers that there are several similar templates, and what documentation they are actually reading.
:::And when not using soft redirects I have many times seen questions like: "''Why does the documentation say {{tlf|foo}} when the template's name is {{tl|foo2}}?''".
:::And I have seen editors "clean away" the info about the other templates, just because they didn't realise the /doc page was shared. Or they have made changes to the /doc that doesn't fit with how the other templates work that use the same /doc. Thus causing ''lots'' of confusing for those that read the documentation.
:::That is, if you click the [edit] link on the green doc box you come to the right /doc page, but there is not much that indicates that you are no longer under the same template name as where you started.
:::And regarding your other idea, to transclude a shared documentation onto the actual /doc pages: That works technically but I think it will be confusing for those that want to edit the documentation. But I admit we often do that partially, for instance we often use a template for the "See also" section since most of the see also links are usually the same for a group of templates. See for instance {{tl|main other}} and its sister templates.
:::And here's a little rant for everyone else reading this (since I think Amalthea already knows this): An important thing to remember when coding and documenting templates here at Wikipedia is that you yourself will not be here forever to maintain your templates, others will have to maintain them after you or when you are on vacation. So try to keep things clear and if possible simple. And hey, if you are an old programmer like me, then you know the value of clear code and documentation when you yourself come back some years later when you have forgotten everything.
:::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 20:54, 7 April 2009 (UTC)
:::: OK, I did it like you recommended.<br>I'm not quite convinced that this is the best way, though. I could see remedies for a number of your issues, like simply mentioning "This is the centralized documentation for {{tl|template 1}} and {{tl|template 2}}" or something at the top.<br>I totally agree on the branchend documentations, {{tl|Db doc}} does that and is an absolute hell.<br>Cheers, [[User talk:Amalthea|<span style="font-family:Verdana;font-variant:small-caps;color:#823824;font-weight:normal">Amalthea</span>]] 09:17, 8 April 2009 (UTC)
:Yes, you are right that if you add a proper lead in the shared documentation it probably reduces the confusion a lot. Note that you still need such a "''This page is the documentation for the templates X and Y''" lead, even if you use soft redirects. Since otherwise people will still do weird edits to the documentation. And it also makes it clear to people who arrived through the redirects that they have come to the right place.
:Ouch! {{tl|db doc}} is a scary example. Yeah, some coders don't understand that documentation is not code, it is text.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 11:30, 8 April 2009 (UTC)
::But I like code {{mono|1=:D}} How else do you suggest we keep the documentation for 48 almost-identical templates up to date?? I do agree with you, {{tlx|db doc}} is a meta-template from hell, but there's no better way to do it IMO. [[User:Happy-melon|<b style="color:forestgreen;">Happy</b>]]‑[[User talk:Happy-melon|<b style="color:darkorange;">melon</b>]] 14:23, 8 April 2009 (UTC)
:::Oh, that's simple: Put all the documentation in one place, then have "soft redirects" from the /doc pages of the other templates. And in the really complex cases you can do as I did with all the wrap templates, make a how-to guide covering it all: [[Wikipedia:Line break handling]].
:::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 10:25, 30 November 2009 (UTC)

== File pages ==
{{Resolved|1=Fixed.}}
I think we also should use /doc pages for protected images, for the exact same reasons that we use /doc pages for templates: We have a problem that non-admins can't update the descriptions of protected images. This means that such pages usually lack links to other similar images, and they lack categorization etc. That can also lock out the uploader himself from updating the description, which can be very frustrating and might discourage further image uploads.

I am doing a test with [[:File:Ambox style.png]], you can see how it looks there. 

Using a subpage directly under the image page didn't work as well as I hoped, since there are tools that interferes with it. (The /doc page got listed as an image page lacking an image.) And the file namespace doesn't have the "subpage feature" enabled, thus there are some other issues. So I have now moved that /doc page to be under the image's talk page instead, I think that should fix it. We mostly access the /doc page using the links in the green doc box created by the {{tl|documentation}} template, so it doesn't matter much where the /doc page actually is placed. And having it under the talk page means it still comes along when we do page moves. 

So if/when we decide to use this, then I would like to update the logic in the {{tl|documentation}} template so it places the /doc page under the talk page, when on a file page.

--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 11:07, 30 November 2009 (UTC)
:''The two messages below are copied from my talk page. --[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 12:01, 30 November 2009 (UTC)''
:: I [[Wikipedia:Wikipedia Signpost/2009-11-16/Technology report|heard]] that images can be protected while the file description page remains unprotected these days: [[bugzilla:6579]]. Doesn't appear to be live yet though. [[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 11:19, 30 November 2009 (UTC)
:::Oh, thanks for the link to the bugzilla bug. And right, it could be nice if they fix it in the software. But I hear people saying that it nowadays takes ages before they deploy fixes, even when the code has already been written for it. (But I don't know from personal experience, since the one time I asked for a fix some year ago, they fixed it and deployed it in 12 hours!!! :))
:::I think we should start using /doc pages for images, since we don't know when the fix will be deployed. And the /doc pages could still be useful in some cases, even after the fix has been deployed, if we admins want to protect parts of the image description.
:::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg#top|talk]]) 11:55, 30 November 2009 (UTC)
:''End, messages copied from my talk page. --[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 12:01, 30 November 2009 (UTC)''
::I have updated the {{tl|documentation}} template: It now automatically places the /doc page under the talkpage when in File space, and automatically shows the heading "Summary" instead of "Documentation". And when clicking the [create] link in an empty doc box it automatically preloads the right content for File pages.
::Most license templates and other image related templates only categorize pages when in "File" space, thus the /doc pages in File talk space don't get categorized by the license templates.
::This means all the technical stuff is in place. See [[:File:Ambox style.png]] for a live example. I would like to start using and promote using {{tlf|documentation}} on protected images. I will announce this discussion in several image related places so people can come here and discuss.
::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 19:45, 12 February 2010 (UTC)
:I was coming here to point out what Amalthea did. The fix is already done in the software and the code has been reviewed. Its only waiting on deployment at this time. I'm really not too keen on the idea of implementing something like this that we know is going to be obsolete imminently. <span style="font-family:Broadway">[[User:Mr.Z-man|Mr.]][[User talk:Mr.Z-man|'''''Z-'''man'']]</span> 23:25, 12 February 2010 (UTC)
::If I remember right, when I started editing Wikipedia many years ago we already had this feature. But it was disabled since admins were confused by it and sometimes protected the description page instead of the image.
::In 2006 [[bugzilla:6579]] was opened with what amounts to a request to re-add the feature. The feature has since been discussed and code has been worked on. The last I can see in that discussion is that the bug has been reopened since it still does not work (more fixes needed). And even when all the code is in place we don't know if the sys-admins will deploy the code and enable the feature.
::So for what we know it might never be enabled, or it might take another four years until it is enabled. And even if/when the feature is enabled, the /doc system won't conflict with it, it will still work fine.
::The /doc system has been used for templates for years now, so we know it works well and people are familiar with it. The /doc system is ready to be used today, right now. Not some time far into the future.
::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 00:09, 13 February 2010 (UTC)
:::The code currently does work, and as I noted, has been reviewed (which is the final step before deployment). At this point the only question is "when?". I don't know for sure when the next code update will be, but I would estimate this would be deployed within the next 2 months, likely sooner. <span style="font-family:Broadway">[[User:Mr.Z-man|Mr.]][[User talk:Mr.Z-man|'''''Z-'''man'']]</span> 00:49, 13 February 2010 (UTC)
::::Short comment: 
::::Our high-risk images are cascade protected, so I think we will still need the /doc system, even if/when r58537 has been deployed.
::::Long comment:
::::Well, I don't know much about bugzilla and such stuff. I see the fix was added in r58537, but Bryan Tong Minh and MZMcBride think it has been disabled in r59419, while you think it means it hasn't been disabled. I hope you are right.
::::But r58537 probably won't fix it for our high-risk images here at enwp. This is a bit comlicated, but here's why:
::::We have many trigger-happy admins that know very little about high-risk image handling, so they go around deleting protected images saying "''there is a copy on Commons, so not needed here''". They don't realise that high-risk images need to be locally uploaded and protected here, for a number of reasons. (Among other things since users and admins at Commons often do changes to the images there that doesn't fit our local needs, sometimes they even rename or delete the image there.) We try to educate our local admins, but we get new admins all the time, so some of the high-risk images are deleted here at enwp on an almost monthly basis. 
::::When a local image is deleted it doesn't help if the image on Commons is protected, since any vandal can upload a rude image locally. To prevent that we have put our most high-risk images on some cascade protected pages so the local image page is protected, no matter if the image exists or is deleted. This helps both while the image is deleted, and if it is restored, since admins often forget to re-protect the images when they restore them.
::::So since several hundreds of our high-risk images are cascade protected, that means their image description pages are also cascade protected. I assume that will not change with r58537, or does that revision include changes to how cascade protection works? My guess is that those image pages won't be editable even when we can unprotect the pages themselves, since they will still be cascade protected. Thankfully the cascade protection doesn't go on to the /doc subpages. For an example of this, try to edit [[:File:Ambox style.png]] and [[File talk:Ambox style.png/doc]]. 
::::So for our high-risk images we will still need the /doc system, even after r58537 has been deployed.
::::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 03:19, 13 February 2010 (UTC)
::::: I do not think that ''when a local image is deleted it doesn't help if the image on Commons is protected, since any vandal can upload a rude image locally.'', because only administrators have '<tt>reupload-shared</tt>' userright. [[User:Ruslik0|Ruslik]]_[[User Talk:Ruslik0|<span style="color:red">Zero</span>]] 08:59, 14 February 2010 (UTC)
::::Putting things on a cascade protected page to protect them like that has been deprecated for a long time (since we got the ability to protect pages from creation). Suggesting we augment an obsolete system with one that's about to become obsolete isn't especially persuasive. <span style="font-family:Broadway">[[User:Mr.Z-man|Mr.]][[User talk:Mr.Z-man|'''''Z-'''man'']]</span> 06:12, 13 February 2010 (UTC)
:I take it you might not be aware of the fairly new [[Wikipedia:Cascade-protected items]], or perhaps don't understand why we need it?
:I just explained in my previous message why it doesn't help that we got the ability to create-protect images. Since (new) admins who doesn't know better go deleting protected high-risk images and don't create-protect the image after the deletion. And if we create-protect it, then when an admin add the image it looses its protection. I consider that a bug, a protected image or page should not become unprotected just because it is deleted or added. It should take an extra manual choice to remove the protection. 
:The only way we have to work around that bug is to add the image to a cascade-protected page, so it continues to be protected no matter what.
:Also, as far as I remember when one deletes a protected image one doesn't get any indication or warning. So some of those admins don't even notice that they are deleting protected images. It seems they don't even see the protection box on the image page or read the image description, since they use tools that delete images from category listings or so.
:And have you ever tried to go through the 1000 most used images and protecting them one by one? It was much faster to simply add them to a cascade page. And as I said, it really doesn't help to protect them by one by one, since the protection isn't persistent.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 07:55, 13 February 2010 (UTC)
::It's fairly obvious to me that cascade-protecting an image by inlining it on a cascade-protected page, should protect the ''image'', not the description page.  I've filed that as {{phab|24521}}.  That would resolve the lingering issues here.
::The protect-file-only code ''is'' live on the latest version of MW, and will appear on WMF wikis at the next scap, which hopefully will be before the end of the month.  [[User:Happy-melon|<span style="color:forestgreen">'''Happy'''</span>]]‑[[User talk:Happy-melon|<span style="color:darkorange">'''melon'''</span>]] 20:01, 14 February 2010 (UTC)

== [[Template:Documentation]] ==
{{FYI|New features have been added to {{tl|Documentation}}.}}
We are planning to do some changes to the {{tl|documentation}} template. We are planning to add (create) links for the /sandbox and /testcases pages when they don't exist. And we are perhaps going to move the sandbox and testcases links and the "''This documentation is transcluded from...''" line to a small box below the big doc box, instead of as now inside at the top of the big doc box. See more about this and discuss it at [[Template talk:Documentation#Documentation/links]].

--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 07:11, 4 February 2010 (UTC)
:{{tick|18}} '''{{ucfirst:Done}}''' - And I have updated and reworked its documentation. --[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 19:47, 12 February 2010 (UTC)

== Template documentation and debugging ==
{{Stale|There is no automated fix for this as of 12/2011; request at MW Bugzilla as a ParserFunctions "magic word" feature?}}
Hi there, I have created {{tl|IPAlink}} and its documentation.

In the documentation, I would like to have a table like this

{| class="wikitable"
|-
! Template invocation !! Returned code !! Rendered as
|-
| <code><nowiki>{{IPAlink|m}}</nowiki></code>
|| <code><nowiki>[[Bilabial nasal|m]]</nowiki></code>
|| {{IPAlink|m}}
|-
| <code><nowiki>{{IPAlink|ɡ͡b}}</nowiki></code>
|| <code><nowiki>[[Voiced labial-velar plosive|ɡ͡b]]</nowiki></code>
|| {{IPAlink|ɡ͡b}}
|-
| <code><nowiki>{{IPAlink|pʰɪk}}</nowiki></code>
|| <code><nowiki>[[IPA|pʰɪk]]</nowiki></code>
|| {{IPAlink|pʰ}}{{IPAlink|ɪ}}{{IPAlink|k}}
|}

Here I have hard-coded the central column, but I would really like to have it auto-populated with whatever the template returns. Is there a way to do that? It would seem strange if not, because how are people debugging more complex templates otherwise? Thanks. [[Special:Contributions/222.145.134.103|222.145.134.103]] ([[User talk:222.145.134.103|talk]]) 09:15, 13 June 2010 (UTC)
:You can use <nowiki>{{#tag:nowiki|{{IPAlink|m}}}}</nowiki>. By the way, it gives the span tags too.--[[User:Patrick|Patrick]] ([[User talk:Patrick|talk]]) 09:55, 13 June 2010 (UTC)
::Cool, thanks! So here's the output
{| class="wikitable"
|-
! Template invocation !! Returned code !! Rendered as
|-
| <code><nowiki>{{IPAlink|m}}</nowiki></code>
|| <code>{{#tag:nowiki|{{IPAlink|m}}}}</code>
|| {{IPAlink|m}}
|-
| <code><nowiki>{{IPAlink|ɡ͡b}}</nowiki></code>
|| <code>{{#tag:nowiki|{{IPAlink|ɡ͡b}}}}</code>
|| {{IPAlink|ɡ͡b}}
|-
| <code><nowiki>{{IPAlink|pʰɪk}}</nowiki></code>
|| <code>{{#tag:nowiki|{{IPAlink|pʰ}}{{IPAlink|ɪ}}{{IPAlink|k}}}}</code>
|| {{IPAlink|pʰ}}{{IPAlink|ɪ}}{{IPAlink|k}}
|}
::Now, wouldn't this be useful for many template docs? I would like to take this to the next natural level and create a couple of templates that do just that. Basically, the template documentation writer would just write:

 <nowiki>{{begin_template_doc_example_table}}</nowiki>
 <nowiki>{{template_doc_example|{{IPAlink|m}}}}</nowiki>
 <nowiki>{{template_doc_example|{{IPAlink|ɡ͡b}}}}</nowiki>
 <nowiki>{{template_doc_example|{{IPAlink|pʰ}}{{IPAlink|ɪ}}{{IPAlink|k}}}}</nowiki>
 <nowiki>{{end_template_doc_example_table}}</nowiki>
::No more repetitions, everyone happy, the end. What do you think, is it possible? Or would the arguments to template_doc_example be evaluated before the template is invoked? [[Special:Contributions/222.145.134.103|222.145.134.103]] ([[User talk:222.145.134.103|talk]]) 11:09, 13 June 2010 (UTC)
:::Yes, the arguments to template_doc_example are evaluated before the template is invoked, but instead you can use the name of the template (here IPAlink) and its parameter as parameters of template_doc_example.
::::We have already {{tiw|xpdop3c}} producing:
:::::{{tl|xpdop3c|IPAlink|m}}
::::or for use in a table
:::::{{tl|xpdop3c|IPAlink|m|gives={{!}}{{!}}|d=}}
::::See also [[m:Help:Expansion demo templates]].--[[User:Patrick|Patrick]] ([[User talk:Patrick|talk]]) 22:53, 14 June 2010 (UTC)
:There is no way to get exactly what you were after automatically. You just have to hand code using {{tl|tlx}} and the like.  The {{nowrap|1={{tnull|&#35;tag:nowiki|{<nowiki />{<var>template_name</var>|<var>parameter1{{=}}value...</var><nowiki>}}</nowiki>}}}} method is useless in template documentation because of all the {{tag|span}} output that will hopelessly confuse matters for most people trying to follow the docs, and the {{tnull|xpdop3c}} output also confusing, with weird links no one needs or expects. This is probably something good to request (after doing a bunch of [https://bugzilla.wikimedia.org/query.cgi searches to make sure it's not already been requested]) at the MediaWiki [[Bugzilla]] as a feature to add to [[MediaWiki]]'s stable of [[mw:Help:Extension:ParserFunctions|ParserFunction]] "[[mw:Help:Magic words|magic word]]" features. It would be very, very helpful if we had something like {{nowrap|1={{tag|noparse|content={{<var>template_name</var>|<var>parameter1{{=}}value....</var>}}}}}} or {{nowrap|1={{tnull|noparse:<var>template_name</var>|<var>parameter1{{=}}value...</var>}}}}, that would transclude a specified template with the given parameters and values without parsing its output, as if transcluding into an on-the-fly {{tag|nowiki}} that doesn't exist in the code. I can think of quite a few uses for that... — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 22:51, 18 December 2011 (UTC)

== Help for less experienced user ==
{{Resolved|1=Question answered.}}
For a beginner, it's very hard to find a template in thousands of them. Is it possible to have a category "Most used templates", so that if one is simply looking for a way to say "this section requires better documentation" or "this page should be split" can find the right templates? --[[User:GianniG46|GianniG46]] ([[User talk:GianniG46|talk]]) 15:11, 15 June 2010 (UTC)
:What you are looking for is [[Wikipedia:Template messages]]. That page and its subpages are better than a category, since it also shows the templates and have some explanations.
:I often forget the name of that page, but it is easy to find: In the menu to the left of all Wikipedia pages click "''Help''", then "''Resources and lists''" (or "''Editing Wikipedia''"), then "''List of templates''".
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 08:36, 30 December 2010 (UTC)
::Remembering the [[W:TEMP]] shortcut is also easy for some people. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:51, 18 December 2011 (UTC)

== Prefer no SHOUTING ==
{{Resolved|1=Moot.}}
I propose this template should do {{allcaps|no shouting}}. <br>
As per [[WP:MOS|Wiki-MOS]], innit. -[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 01:14, 19 August 2010 (UTC)
It doesn't. 
:The formatting that {{tl|Documentation}} has had for a long time makes no use of ALL-CAPS, manually nor via {{tl|allcaps}} markup. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:48, 18 December 2011 (UTC)

== How about sub-template /pages in a Template? ==
{{Resolved|1=Question answered.}}
The current do & don't list says about Templates: "subpage for documentation allowed". What does this mean for sub-pages that are templates? Examples: [[:Category:Extended Convert subtemplates]] and {{tl|ambox/core}}? -[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 07:47, 6 September 2010 (UTC)
:Nothing. There wasn't anything exclusive implied, and it's probably a reference to the fact that /subpages are not allowed in mainspace (in Wikipedia, where this means articles; they are permitted in many other wikis, including Meta).  Sub-templates on /subpages are common practice for any templates that get excessively complex, or where multiple templates need to re-use the same code. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:46, 18 December 2011 (UTC)

== Defaultsort does not work ==
{{Unresolved|1=Has only been fixed in [[Template:Documentation subpage]].}}
''The subpage template sets a <NOWIKI>{{DEFAULTSORT:{{PAGENAME}}}}</NOWIKI> ensuring that a <CODE>Template:X</CODE> will be properly sorted at "X" and not "T", it is thus not useful or desirable to add a <NOWIKI>{{PAGENAME}}</NOWIKI> sortkey to the categories.'' - Obviously, this does not work properly. e.g. {{tl|music}} is sorted under "T" instead of "M". --[[User:FordPrefect42|FordPrefect42]] ([[User talk:FordPrefect42|talk]]) 11:30, 10 February 2008 (UTC)
:Ah, you are right. I checked the code for {{tl|documentation}} and there is no {{tlc|DEFAULTSORT:{{tlf|PAGENAME}}}} there. I also checked {{tl|documentation subpage}} and it has such code but in the wrong part of the #ifeq statements so it never gets used on the template pages, only on the /doc pages. I'll have to take a closer look at it and think for a while before I fix it. I think that code should be added to both {{tlf|documentation}} and {{tlf|documentation subpage}} since not all pages use both and the /doc pages need good default sorting themselves.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 18:06, 17 April 2008 (UTC)

== How to do good inline documenting ==
{{Resolved|1=Question answered.}}
Hi, is there some help available on how to document a template inline (in code), e.g. by using <code><nowiki><!-- comments & newline & indent--></nowiki></code>? Is it good practice to add many comment text to clarify, or is there a basic level of insight we might expect? Good example templates maybe? -[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 00:28, 23 January 2011 (UTC)
:There's no written standard, and very little is done in this area. MediaWiki template and ParserFunction syntax is so simple that commenting is rarely needed, and because it has to be done in HTML comments, it is tedious, messy, and easy to break.  Indentation and linebreaking just for code beautification often has unintended consequences on the output if you're not careful.  Complex templates like {{tl|WikiProjectBannerMeta}} make use of it, but general practice for templates that don't need an {{tl|Intricate template}} warning is to keep the code as concise and compact as possible, since template are transcluded, sometimes millions of times per day. They are not like computer program source code that can be longwinded, but gets reduced to lean, fast machine language after being compiled once. MediaWiki has to parse it character by character every single time, so characters in the code that are not necessary are, in the aggregate, a non-trivial matter, even if one inefficient template isn't going to break anything. Talk pages are cheap, so if anything is unusual about the code, it can be noted on the template's talk page (probably not in its documentation, which is usually for editors writing articles, not for meta-editors maintaining templates). — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:42, 18 December 2011 (UTC)

== Why does the preload text differ from that suggested in [[WP:DOC]]? ==
{{Resolved|1=Fixed.}}
So, [[Wikipedia:Template documentation#How_to_create_a_documentation_subpage]] suggests one hunk of text be used in /doc subpages, and [[Template:Documentation/preload]] contains a 'different' block of text which is preloaded into the editbox when one actually goes to create such a page. How is an editor supposed to know which to use?

Might it not be better if these were merged, so that [[Wikipedia:Template_documentation]] would transclude the source of [[Template:Documentation/preload]] into a <code>&lt;pre></code> somehow (with a nearby hyperlink to that page to facilitate editing), rather than containing an out-of-sync suggestion for what to put there?

Or I suppose that code could be removed entirely from the page, though that might make things harder for those who might wish to use it as an example from which to update old /doc subpages...

Regardless, this seems gratuitously confusing.
&mdash;[[User:SamB|SamB]] ([[User talk:SamB|talk]]) 22:10, 7 June 2011 (UTC)
:I synched the instructional text to use the actual transclusion code.  I tinkered, but I can't think of a way to actually transclude the code from [[Template:Documentation/preload]] into the instructional text without it also processing as a transcluded template. [[Wikipedia:Template_documentation]] will just have to be periodically checked for conformance with the "live" code in {{tnull|Documentation/preload}}. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:29, 18 December 2011 (UTC)
::I've experienced a problem when [http://en.wikipedia.org/w/index.php?title=Wikipedia%3ATemplate_documentation&action=historysubmit&diff=466584477&oldid=462129874 this edit] was implemented. Under the section "How to create a documentation subpage" the code for the includeonly's does not work. See [http://en.wikipedia.org/w/index.php?title=Template:User_Missoula/doc&oldid=469370360 this edit], which shows that there are 2 extra, orphaned "includeonly" tags at the bottom left of the /doc pg. Since the old instructions worked, I'd like to update the instructions to include the revision that worked before. --[[User:Funandtrvl|Funandtrvl]] ([[User talk:Funandtrvl|talk]]) 19:31, 3 January 2012 (UTC)
:::Why not just fix the error?  But, by all means revert to something that worked in the interim. I would just go fix this stuff myself right now, but I'm on my way out the door... — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 21:35, 3 January 2012 (UTC)
::::No problem, in the meantime, I did update the instructions. Thanks, --[[User:Funandtrvl|Funandtrvl]] ([[User talk:Funandtrvl|talk]]) 23:33, 3 January 2012 (UTC)
:::::Fixed. Properly, this time. — <span style="font-family:Trebuchet MS;">'''[[User:SMcCandlish|SMcCandlish]]'''   <span style="white-space:nowrap;">[[User talk:SMcCandlish|Talk⇒]] ʕ(<sup>Õ</sup>ل<sup>ō</sup>)ˀ</span>  <small>[[Special:Contributions/SMcCandlish|Contribs]].</small></span> 01:12, 5 January 2012 (UTC)

== Remove implicit reference to "pre-expand include limit" ==

In the last paragraph of the "What to include" section, this guide says:
:Text on the template page itself adds to the amount of text that must be processed when displaying the template, which is [[Wikipedia:Template limits|limited]] for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have <span class="plainlinks">[http://en.wikipedia.org/w/index.php?title=Wikipedia:Village_pump_(technical)&diff=prev&oldid=69888944 recommended]</span> it for this reason).
However, following the link and reading all the way to the bottom at [[WP:Template limits#History]], we see:
:The inclusion limits were put into effect on the English Wikipedia by [[User:Tim Starling|Tim Starling]] on 14 August 2006. A new preprocessor was enabled in January 2008, removing the "pre-expand include limit" and replacing it with a "preprocessor node count" limit.

:The practice of using a template documentation page, while it can still be useful for other reasons, is no longer needed for avoiding documentation to be counted on pages that call the template.

So it seems that this paragraph should be removed or replaced. [[User:Set theorist|Set theorist]] ([[User talk:Set theorist|talk]]) 04:41, 13 March 2012 (UTC)

:Well, I didn't mean that the whole paragraph should be removed, as certainly the first sentence is correct.  I meant that the two sentences I quoted should probably be removed. [[User:Set theorist|Set theorist]] ([[User talk:Set theorist|talk]]) 04:44, 13 March 2012 (UTC)

== Section heading levels on doc pages ==

Is there any basis for template documentation pages not to have level 2 section headings as required by [[MOS:LAYOUT#Headings and sections]]?  I've seen a number of doc pages that start with level 3 headings. [[User:Set theorist|Set theorist]] ([[User talk:Set theorist|talk]]) 07:15, 26 March 2012 (UTC)
: Can we have an answer to this please? Every doc subpage I have looked at has level 3 headings including that for {{tlx|Documentation}}, so it rather looks as if these instructions should be corrected. --[[User:Mirokado|Mirokado]] ([[User talk:Mirokado|talk]]) 23:46, 23 October 2012 (UTC)
::At present, [[Wikipedia:Template documentation#How to create a documentation subpage]] shows (but does not explicitly state) to use level 2 headings; and if you set up a template for a doc page by adding {{tag|noinclude|content={{tl|documentation}}}} to the bottom, and then click the "create" link at upper right of the new doc box, the new doc page is pre-filled from [[Template:Documentation/preload]], which also uses level 2 headings. The preload feature has used level 2 for {{diff|Template:Documentation/preload|prev|461769218|the last eleven months}}, so doc pages using level 3 headings were probably created before then.
::If you look through the [//en.wikipedia.org/w/index.php?title=Template:Documentation/preload&action=history revision history] for the preload, you'll see that there has been much disagreement. Some of the edit summaries point to discussion elsewhere, which may have been archived (although as I recall, some were quite extensive).
::Until and unless both [[WP:DOC]] and the preload change again, I would therefore use level 2 for ''new'' doc pages; do not change existing doc pages from level-2 style to level-3 style; but be careful of changing existing doc pages from level-3 style to level-2 style, since you might provoke an adverse reaction. --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 09:04, 24 October 2012 (UTC)

== half-listing cat in noinclude ==

Where the page says, "to place the doc subpage into a category, add the <code><nowiki>[[Category:Category name]]</nowiki></code> code inside a <code><nowiki><noinclude></nowiki></code>...<code><nowiki></noinclude></nowiki></code> section on the doc subpage" (boldfacing and italics omitted), I added, "the category won't be listed on the doc page but the category will list the doc page." This was [//en.wikipedia.org/w/index.php?title=Wikipedia%3ATemplate_documentation&diff=582180982&oldid=582106515 reverted] because, according to an editor, "the cat is shown at the doc page even if inside <nowiki><noinclude></noinclude></nowiki> - it's <nowiki><includeonly></includeonly></nowiki> that prevents this". In that case, something else must be causing [[Template:Subscription or libraries/doc|one doc page]] to not list [[:Category:Template documentation pages|one category]] although the [//en.wikipedia.org/w/index.php?title=Category:Template_documentation_pages&from=Su category lists the doc page]. Whether I have [//en.wikipedia.org/w/index.php?title=Template:Subscription_or_libraries/doc&diff=582105012&oldid=582089786 line breaks around the category link] or [//en.wikipedia.org/w/index.php?title=Template:Subscription_or_libraries/doc&diff=580188911&oldid=580069172 not] does not matter. Is something wrong with the doc? [[User:Nick Levinson|Nick Levinson]] ([[User talk:Nick Levinson|talk]]) 17:29, 18 November 2013 (UTC)
:Line breaks do not make any difference to categorisation. The {{tag|noinclude}} tags prevent ''transclusion'', not processing, of enclosed content. I think I know why you don't see it... it's a [[WP:HIDDENCAT|hidden category]]. Go to {{myprefs|Appearance}}, and under "{{int:prefs-advancedrendering}}", enable "{{int:tog-showhiddencats}}". --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 20:38, 18 November 2013 (UTC)
::Thank you, I now see that it's a hidden category, and I can add that explanation to the how-to page, although the [[Wikipedia:Categorization#Hiding categories|WP:HIDDENCAT]] guideline says hiding occurs if <nowiki>{{Wikipedia category|hidden=yes}}</nowiki> or <nowiki>__HIDDENCAT__</nowiki> is in the page source code, but neither one is. However, according to [[:Category:Hidden categories]], any subcategory of a hidden category is also hidden, and that applies here. The [[Template:Wikipedia category/doc|doc for Template:Wikipedia category]] should state that principle and I can take care of that. Do you think there's any problem with these two edits? [[User:Nick Levinson|Nick Levinson]] ([[User talk:Nick Levinson|talk]]) 17:14, 19 November 2013 (UTC)
:::Being hidden is not inherited. It was a hidden category because of the rather strange presence of {{tlx|DYKT}}, which brings in {{tlx|tracking category|2=container=yes}}, and if you go deep enough, you'll find that it adds <code><nowiki>__HIDDENCAT__</nowiki></code>. The {{tlx|DYKT}} was added by {{user|John Cline}}. I have {{diff|Category:Template documentation pages|prev|582421188|reverted it}} because {{cl|Template documentation pages}} is nothing to do with DYK, and is not a tracking category either. --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 20:27, 19 November 2013 (UTC)
::::Okay and thanks; at the moment I won't do either of the edits. That leaves me wondering what the basis for the claim of subcategories being hidden is, and I've begun a [[Category talk:Hidden categories#inheritance by subcats|talk topic/section about it]], albeit on a page that doesn't get looked at much. [[User:Nick Levinson|Nick Levinson]] ([[User talk:Nick Levinson|talk]]) 18:08, 20 November 2013 (UTC)
:::::The page [//en.wikipedia.org/w/index.php?title=Category_talk:Hidden_categories&action=info#mw-pageinfo-watchers has 74 watchers], myself included; I've replied there. --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] ([[User talk:Redrose64|talk]]) 20:05, 20 November 2013 (UTC)

== Comments in the code - still necessary? ==
:''Follow-up to [[WP:VPT#Can we please get rid of those shouty comments in template documentation?]]''
I find the instructional comments in the [[Template:Documentation/preload|code]] to be of little use, to be honest, and a source of much clutter around the project. There's already {{tl|Documentation/doc}}, and that, to me, is where instructions like "{{code|Add categories to the /doc subpage and interwikis in Wikidata}}" should be - not copied and pasted thousands of times around the project in source code. In there they're most likely to only be seen by experienced template editors, anyway, and they don't need to be told over and over again. (It's even worse for older template documentation templates, because until February 2011 the comments were all {{diff|diff=prev|oldid=413228483|label=IN CAPITALS!}} which is really annoying.) If categories get added to a template rather than its documentation by an inexperienced user, the mistake will almost certainly be caught swiftly; and interwiki additions will get zapped by some bot or other. So, as far as I can see it, the comments are largely redundant. They even give us maintenance overhead: because they're copied every time, if a change needs to be made, it can't be done by only editing one template. That's {{diff|diff=590803752|label=already making work for people}}.

I propose, for the sake of clean source code and maintainable documentation, that we remove the comments from the preload template, and ensure that the documentation explains properly how to use template categories and interwiki links. Then, we recruit a bot to hoover up all the places where they got in since their introduction in 2006. What do you think? — [[User:Scott Martin|'''<span style="color:#000">Scott</span>''']] <span style="color:#900">•</span> [[User talk:Scott Martin|''<span style="color:#000">talk</span>'']] 16:26, 17 January 2014 (UTC)
:I see your point, but I still think the comments are useful in the code. You're an experienced editor, so you know what to do, but I still see lots of templates that have duplicate categories both on the temp page and the doc page, and I still see missing "noinclude" and "includeonly" only tags on those same pages, and I've cleaned up a lot of templates! I think w/o the code, there may be even more mistakes to be cleaned up. [[User:Funandtrvl|Funandtrvl]] ([[User talk:Funandtrvl|talk]]) 18:23, 17 January 2014 (UTC)
::That's what bots are for! — [[User:Scott Martin|'''<span style="color:#000">Scott</span>''']] <span style="color:#900">•</span> [[User talk:Scott Martin|''<span style="color:#000">talk</span>'']] 22:06, 18 January 2014 (UTC)

==Prevent /sandbox categorisation==
Code 
<pre>
{{#ifeq:{{SUBPAGENAME}}|sandbox||

}}
</pre>

better be replaced by
<pre>
{{sandbox other||

}}
</pre>

for reasons of 1. central control, 2. clarity for editors, 3. future improvement (eg, include pages "X/sandbox/version2"?). -[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 22:22, 17 April 2016 (UTC)
-[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 22:22, 17 April 2016 (UTC)


*I see the suggested code has been changed to:
<pre>
{{#ifeq:{{SUBPAGENAME}}|sandbox||{{#ifeq:{{SUBPAGENAME}}|testcases||
<!-- categories go here -->
}}</pre>
:Shall we adjust & move {{tl|sandbox other}} accordingly? -[[User:DePiep|DePiep]] ([[User talk:DePiep|talk]]) 20:30, 25 May 2016 (UTC)

== Markup short cut ==

By using the template [[Template:Mra]], one can create [[Template:Markup]] syntax with each example entered once only. [[User:Iceblock|Iceblock]] ([[User talk:Iceblock#top|talk]]) 11:49, 31 July 2016 (UTC)

== Doc subpages and performance ==

I've removed [https://en.wikipedia.org/w/index.php?title=Wikipedia:Template_documentation&diff=912506382&oldid=895485130] several sentences that recommend the creation of separate doc subpages for performance reasons. This is because they're based on a technical limit that appears to have been removed in 2008, as was pointed out in [[Wikipedia:Village_pump_(technical)/Archive_173#Should_all_templates_have_their_documentation_as_a_separate_subpage?|this recent village pump thread]]. However, this doesn't mean performance considerations should be completely absent though: as noted in the same discussion, editing a template triggers the reparsing of all pages that transclude it, while editing the doc subpage does not. Should there be a mention of that here? As far as I can see, the performance impact is going to be meaningful only for very heavily used templates, and these are always protected and so have doc subpages, and for reasons that are not related to performance.  – [[User talk:Uanfala|Uanfala (talk)]] 02:17, 26 August 2019 (UTC)

== When should the documentation be in a separate subpage? ==

It's clear that there should be a separate doc subpage if the template is protected, or when its code is very complex. But beyond that, when is it desirable to move the documentation into a subpage and when is it better to leave as it is? There's [[User:Paine Ellsworth|one fellow editor]] who has been steadily working to split off the documentation of many templates, and whenever they've done that to one or another of the navboxes or sidebars on my watchlist I've usually found that unhelpful. A separate doc subpage comes with some disadvantages: 1) it's going to have fewer watchers than the template and so unhelpful edits are less likely to get noticed; 2) it can get left behind if the template is moved (and so its documentation will break); 3) it's a bit less intuitive for new editors to figure out how to edit.

Granted, these aren't huge harms, but they become relevant if there are no benefits to balance them out. Performance was once given as a consideration, but for the majority of templates the effect is negligible (see previous thread). Overall, my opinion is that a template's documentation shouldn't be moved to a separate subpage unless there's a good reason. But what do others think? – [[User talk:Uanfala|Uanfala (talk)]] 02:42, 26 August 2019 (UTC)

:Just a little note that when there is no /doc page, and {{tl|Documentation}} is added to the bottom of a template, there is a "Create" link that leads to a preloaded template page where a separate /doc page can easily be created. That template page starts out looking like this:
<pre>
{{Documentation subpage}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
== Usage ==


<includeonly>{{sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>
</pre>
:Since somebody went to the trouble of creating/designing this useful template, it probably means that there are many editors who know about it and who use it, especially to ensure that edits made to a separate /doc page do not require the reparsing of the template on all pages that transclude it. Frankly, I've been creating /doc pages for nearly ten years and have considered every /doc page I've made to be a helpful addition to this project. Can't understand why anyone wouldn't. Advantages far outweigh any perceived "harms", in my humble opinion. '''''[[User:Paine Ellsworth|<span style="font-size:95%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>03:29, 26 August 2019 (UTC)</small>
:{{replyto|Uanfala}} How often does (2) occur?
:Also, if the documentation needs certain kinds of markup - such as tables - you can use regular Wikimarkup when it's a separate doc page, but not when it's placed in a {{para|content}} parameter in the main template, for which you need to jump through hoops like {{tlx|!}}. --[[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]] &#x1f339; ([[User talk:Redrose64|talk]]) 08:04, 26 August 2019 (UTC)
::Hi [[User:Redrose64|<span style="color:#a80000; background:#ffeeee; text-decoration:inherit">Red</span>rose64]], I've seen (2) happen on rare occasion usually as the result of an inexperienced editor moving a template page I watch. I go ahead and move the /doc page and then notify the editor to be sure to look for /doc, /sandbox and /testcases pages that also may need to be renamed when they move a template. '''''[[User:Paine Ellsworth|<span style="font-size:95%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>12:18, 27 August 2019 (UTC)</small>
:::{{u|Paine Ellsworth}}, it's a good idea not to go on with the mass creation of subpages for the duration of this discussion. And please, there's no need to start edit warring on the occasional pages you've been reverted. – [[User talk:Uanfala|Uanfala (talk)]] 00:51, 3 September 2019 (UTC)
::::No, it's a good idea for you to stop reverting until and unless you achieve a community consensus against the creation of helpful /doc pages for templates. And be careful about serious accusations of behavior, as well''!'' (It takes two to tango.) '''''[[User:Paine Ellsworth|<span style="font-size:95%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>00:56, 3 September 2019 (UTC)</small>

*Bringing this up again. {{u|Paine Ellsworth}} has again become very persistent in moving the docs into separate subpages, and has reverted any reverts of their actions on individual templates, insisting that consensus was on their side. Now, if really the community consensus is that all and every template should have its documentation on a separate subpage, and if anyone who disagrees with this on any individual template should be ignored and reverted, then I would like to have that consensus given explicitly somewhere. And if the community consensus is not that, then it will be appreciated if someone could tell Paine Ellsworth that if they really insist that a given template should have a separate /doc page, then they should gain consensus from the editors who look after that template and not edit-war with them. – [[User talk:Uanfala|Uanfala (talk)]] 01:58, 9 November 2019 (UTC)
**You say I've {{"'}}again' become very persistent in moving the docs into separate subpages". Not really "again", because I do what I've been doing for ten years or more. And I'm not the only one, just apparently the only one you revert against a solid community consensus that recognizes the important benefits of useful and helpful separate /doc pages. We can only hope that you will begin to understand this. Don't know why you've decided to pursue such a way, but I hope you will learn to see why it is a good thing to have usually brief, separate /doc pages for many, many templates. You've been given the reasons in these discussions you've started, you've been reminded that there is a <span class="plainlinks">[https://en.wikipedia.org/w/index.php?title=Template:Preloaded/doc&action=edit&preload=Template%3ADocumentation%2Fpreload documentation preload template]</span> that has been around for a long time and that makes it very easy to create separate /doc pages, and you still continue to edit against consensus. Please put an end to this before we both get blocked for edit warring''!'' (and a gentle reminder that when editors are in war mode, administrators do not have to wait for [[WP:3RR|3RR]] to kick in – they can block even after just one or two reverts if they think edit warring is taking place) '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>10:59, 9 November 2019 (UTC)</small>
***The choice between having the documentation on the template itself or on a separate page depends on several factors, and in each case editors should evaluate them and exercise their judgement in deciding whether to opt for one or the other. That's my view at least. And if the consensus indeed is that one of the options should be used indiscriminately for all templates, even in the face of opposition from the editors who maintain the template in question, then we need that to be explicit. – [[User talk:Uanfala|Uanfala (talk)]] 11:56, 9 November 2019 (UTC)
****You make it sound as if I always add separate-page documentation to all templates I come across, which I do not. And that is because I agree that not all templates require a separate /doc page. You also make it sound like you are a member of that elite group of "editors who maintain the template in question" and I am not, which is also untrue because I've been [[Wikipedia:WikiProject Languages|watching and maintaining language templates]] for quite some time. Let's look at the two most recent templates that you've decided don't need separate /doc pages, {{tl|Indo-Aryan languages}} and {{tl|Languages of Northeast India}}. Both of those templates are large with a lot of navigational links in them. You seem to think that even with all those transclusions, it is better to not have a separate /doc page, which means that if an editor makes changes to the on-template documentation, those templates must be reparsed on every page they are transcluded. Why do you think that's better than having a separate /doc page, so that when an editor makes changes, the templates do not have to be reparsed on every page they are transcluded? '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>12:28, 9 November 2019 (UTC)</small>
*****The prevention of reparsing is relevant when the template is used on a large number of pages and its documentation is frequently edited. That's not the case for the two navboxes: like with most navboxes, their documentation consists entirely of the {{tl|collapsible option}} boilerplate and some categories, and it gets edited pretty much never. – [[User talk:Uanfala|Uanfala (talk)]] 12:37, 9 November 2019 (UTC)
******So we see at least one point of contention in that I think those two templates are used on a '''large enough''' number of pages. Also, one of us refuses to exhibit such an intricate knowledge of the future when it comes to editing anything on Wikipedia. Congratulations on your acquisition of your crystal ball''!'' '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.&nbsp;I.&nbsp;Ellsworth</span>]]''''',&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>18:46, 9 November 2019 (UTC)</small>

== Wikipedia:TemplateData ==

Nowadays, TemplateData is included in all the templates and it is a good procedure filling its parameters in the documentation,  so it would be good including a link to [[Wikipedia:TemplateData/Tutorial]] in the lead section. --[[User:BoldLuis|BoldLuis]] ([[User talk:BoldLuis|talk]]) 10:09, 3 May 2020 (UTC)

== documentation automatically included in all templates ==

{{tl|documentation}} would be included by default in all the templates, excepting when {{tl|noincdoc}} (or similar code) is used (I think there is no reason to exclude documentation in templates anyway).

The same for the TemplateData content, including its template detected parameters, when the documentation page is automatically created (just after template creation). --[[User:BoldLuis|BoldLuis]] ([[User talk:BoldLuis|talk]]) 11:08, 3 May 2020 (UTC)

== Notice of new template {{tl|Param value}} for assistance in template doc pages ==

I had a need for a way to highlight param values on template doc pages, which could not easily be achieved by use of the &lt;code> tag, which I had been using previously.  The use case was the documentation for {{tl|Lorem ipsum}}, which has some parameters whose values may contain leading and trailing blanks; needless to say, it's particularly hard to see those. An example is: {{param value| * " }}. The new template {{tl|param value}} was my attempted solution for this problem. You can see some examples of it in use at [[Template:Lorem ipsum#Prefix and suffix whitespace]]. [[User:Mathglot|Mathglot]] ([[User talk:Mathglot|talk]]) 10:32, 8 August 2021 (UTC)

== Including TemplateData ==

This page doesn't say where or how to put the TemplateData, even though [[Template:Infobox_person#TemplateData|many]] [[Template:Cite web#TemplateData|many]] templates use a standard format (seen below). I suggest this page include it in the [[Wikipedia:Template documentation#Manual creation|#Manual creation]] section, and in the prefilled creation link provided by {{tl|documentation}}, and putting it at the very bottom of the documentation subpage. There was also a [[Template_talk:Documentation/Archive_8#Integrating_TemplateData|discussion]] nearly 8 years ago on what a standard should be, for those curious. Adding the templatedata section can remind and encourage editors to add it for use in the VisualEditor. Agree? Disagree? Thoughts?

<pre><nowiki>== TemplateData ==
{{TemplateData header}}

<templatedata>
    ...
</templatedata></nowiki></pre> [[User:SWinxy|SWinxy]] ([[User talk:SWinxy|talk]]) 06:02, 23 November 2021 (UTC)
{{block indent|em=1.6|1=<small>Notified: [[Template talk:Documentation]]. [[User:SWinxy|SWinxy]] ([[User talk:SWinxy|talk]]) 06:13, 23 November 2021 (UTC)</small>}}<!-- Template:Notified -->

:Disagree with placing it at the bottom of the page. TemplateData is used for parameter information so should be right next to the parameter section (or its sub-section). There is no reason at all to jump from one side of the page to another to update the same thing. [[User:Gonnym|Gonnym]] ([[User talk:Gonnym|talk]]) 06:30, 23 November 2021 (UTC)
::Good point; it should be right below a parameter section, even though it is usually ''is'' the last thing. [[User:SWinxy|SWinxy]] ([[User talk:SWinxy|talk]]) 06:36, 23 November 2021 (UTC)
:::I've created or edited many template /doc pages and that is rarely true. I typically view it as: Lead (what this template is) -> usage -> parameters -> template data -> examples -> sub-templates -> tracking categories -> -> see also -> categories. [[User:Gonnym|Gonnym]] ([[User talk:Gonnym|talk]]) 06:39, 23 November 2021 (UTC)
*I'm going to take the same line I did eight years ago. Template data should have a default page that {{tlx|documentation}} can automatically transcludes to enable any tools using template data that expect it at /doc to continue working. But data intended for parsing by machine should have its own place; only human readable content should be in /doc. [[User:Vanisaac|Van]][[User talk:Vanisaac|Isaac]], MPLL<sup> [[Special:Contributions/Vanisaac|cont]]</sup><sub style="margin-left:-3.5ex"><small>[[WP:WPWR|WpWS]]</small></sub> 06:04, 24 November 2021 (UTC)
* Agree with Vanissac; separate page, transcludable by {{tlc|documentation}}. Make it harder for non-coders to inadvertently break it, and easier for coders to find it. [[User:Mathglot|Mathglot]] ([[User talk:Mathglot|talk]]) 09:03, 24 November 2021 (UTC)

== Subpage or not ==

There are two places where a template's documentation can go: either on the template page itself, or in a separate subpage. Both are currently mentioned in this guide and both are widely used.

As clearly explained here, subpages are advisable for templates that are protected, have complicated code, or are widely used. What is not explained, however, is that for templates that don't fall into either of these three categories, a subpage is not necessary, and it may in fact be unhelpful because it comes with some practical drawbacks:
*A subpage will have fewer watchers, so vandalism is less likely to get noticed (this is mostly relevant for navboxes, because their documentation is [[Template:vte|directly reachable]] from mainspace).
*A subpage can get stranded after a move, which will break the documentation, without it being obvious to many editors how to fix it.
*The documentation can no longer be edited from the usual "Edit" tab at the top, and it may not be obvious to regular editors what to do instead.

Why am I bringing this up? From [[Wikipedia:Templates for discussion/Log/2022 February 18#Template:Indo-Aryan languages/doc|this recent TfD]] it's apparent that a few editors insist that a separate subpage is the better option under all circumstances, while from a perusal of the recent page creations in the template namespace, it looks like some are splitting out the documentation into subpages as a matter of course for all sorts of templates.

Where do we stand on this question? I believe that creating subpages should be encouraged where it's needed, and discouraged where it's not. The section [[Wikipedia:Template documentation#Where to place it]] could do with an explanation of the cases where subpages are not necessary. – [[User talk:Uanfala|Uanfala (talk)]] 15:31, 23 February 2022 (UTC)
*Case-by-case.  Having a /doc page is almost always the best choice for protected templates; while noincluded on-page documentation is usually fine for very small templates and low-use templates. — [[User:Xaosflux|<span style="color:#FF9933; font-weight:bold; font-family:monotype;">xaosflux</span>]] <sup>[[User talk:Xaosflux|<span style="color:#009933;">Talk</span>]]</sup> 16:05, 23 February 2022 (UTC)`
*This discussion has been preceded by previous discussions: [[Template talk:Indo-Aryan languages|here]], [[Template talk:Old and Middle Indo-Aryan|here]], and [[Wikipedia_talk:Template_documentation/Archive_2#When_should_the_documentation_be_in_a_separate_subpage?|two years ago on this very page]]. I don't mind having documentation in {{para|content}}, but there are good reasons to have separate documentation subpages, including being able to use table markup, and being able to edit the documentation without forcing the template to be reparsed on every page that transcludes it, and being able to let regular editors edit documentation of a protected template. Also, it makes the template page itself much tidier to have only {{tl|documentation}} in the noinclude tags rather than forcing editors to try to figure out where the template ends and the documentation begins. Once a /doc page exists and is used by a template, I don't see a good reason to orphan that subpage and make the template page more complicated. – [[User:Jonesey95|Jonesey95]] ([[User talk:Jonesey95|talk]]) 16:20, 23 February 2022 (UTC)
*Separating documentation from code is good design. It allows for other bots and tools to find and parse/search/edit documentation pages across the site. Plus reasons noted by Jonesy95. There might be a few cases I don't know but generally I think there has to be some good reason not to have /doc.  -- [[User:GreenC|<span style="color: #006A4E;">'''Green'''</span>]][[User talk:GreenC|<span style="color: #093;">'''C'''</span>]] 16:36, 23 February 2022 (UTC)
**{{u|GreenC}}, could you give examples of bots or tools that rely on the documentation being on a separate subpage? – [[User talk:Uanfala|Uanfala (talk)]] 14:58, 3 March 2022 (UTC)
**:If we knew that, we could tell them not to do that, but, that's the point we don't and can't know. It makes programming harder, searching more difficult, creates higher level of complexity in the system, greater chance of things being overlooked or skipped. It's bad design. -- [[User:GreenC|<span style="color: #006A4E;">'''Green'''</span>]][[User talk:GreenC|<span style="color: #093;">'''C'''</span>]] 15:58, 3 March 2022 (UTC)
* Having our documentation on a different page for every one of our 115 <em>thousand</em> navboxes does no-one any good. All it does is introduce opportunity for more vandalism. (I remain waiting for MCR to fix this issue for us.) I'd !vote to delete the examples as well given their triviality. --[[User:Izno|Izno]] ([[User talk:Izno|talk]]) 18:16, 23 February 2022 (UTC)
*:Can doc pages such as 115k nav pages be protected? It sounds like the reason to put docs in the template is to piggyback the page protection it affords. It's the same if the protection is on the doc page or the template page.  -- [[User:GreenC|<span style="color: #006A4E;">'''Green'''</span>]][[User talk:GreenC|<span style="color: #093;">'''C'''</span>]] 15:50, 3 March 2022 (UTC)

== Doc subpage notice on redirects ==

Anybody know an easy way to remove the relatively new automatic doc subpage notice from redirects? {{-r|Module:Infobox3cols/doc|Here's an example}}. Don't think that's really needed on redirects, is it? '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.I.&nbsp;Ellsworth</span>]]'''''&thinsp;,&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>16:00, 19 July 2022 (UTC)</small>
:It doesn't show up in preview. Weird. Is it being inserted by MediaWiki? – [[User:Jonesey95|Jonesey95]] ([[User talk:Jonesey95|talk]]) 18:02, 19 July 2022 (UTC)
::Apparently, yes. And a fairly recent addition, at least to redirects. Should be a way to code it off of redirects if we can find the MW page it's on. '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.I.&nbsp;Ellsworth</span>]]'''''&thinsp;,&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>15:13, 20 July 2022 (UTC)</small>

::{{to|Jonesey95}} asked for help at [[Wikipedia:Village pump (technical)#Template doc header]] – I think the interface page that transcludes the {{tl|Documentation subpage}} template is at [[MediaWiki:Scribunto-doc-page-header]], but I'm not certain of that. '''''[[User:Paine Ellsworth|<span style="font-size:92%;color:darkblue;font-family:Segoe Script">P.I.&nbsp;Ellsworth</span>]]'''''&thinsp;,&nbsp;[[Editor|<span style="color:black">ed.</span>]]&nbsp;[[User talk:Paine Ellsworth|<sup>put'r&nbsp;there</sup>]]&nbsp;<small>12:19, 21 July 2022 (UTC)</small>

== discussion at [[Template talk:High-use]] ==

Please see {{slink|Template talk:High-use|Different wording?}}.

—[[User:Trappist the monk|Trappist the monk]] ([[User talk:Trappist the monk|talk]]) 14:43, 24 November 2022 (UTC)