Template talk:Documentation/Archive 2

Archive 1

Archive 2

Archive 3

Archive 4

Archive 5

{{Documentation, template}}'s final fate

{{Documentation, template}} was created to hide behavior and visual differences between the {{Template doc}} and {{Documentation}} families while Merge Phase 1: service templates was in progress.

All behavior variations are implemented in {{Documentation}} controlled by new optional parameters to be documented later.

The visual differences are implemented in {{Documentation, template}} which trancludes {{Documentation}}.

The behavior overrides were in {{Template doc}} and {{Template doc inline}} and both transclude {{Documentation, template}} for their classic look.

Merge Phase 2: client templates is upon us making this the optimum moment to decide {{Documentation, template}}'s final fate.

Costs avoided

• Consensus debate regarding changed visual look.
• {{Documentation, template/doc}} transcludes {{Documentation/doc}}.
• {{Documentation, template}} inherits {{Documentation}} improvements.

Costs imposed

• Client templates are 1 transclude away from {{Documentation}}
• Adding new-parameter with no default to {{Documentation}} requires editing {{Documentation, template}} from

  {{ Documentation | heading=...}}

  to

  {{ Documentation | heading=...| new-parameter={{{new-parameter|}}}}}

  then within {{Documentation}} new-parameter is always defined causing

  {{{new-parameter|some-value}}}

  to ignore some-value and require

  {{ #if: {{{new-parameter|}}} | {{{new-parameter}}} | some-value }}

  to maintain expected behavior.
• Adding new-parameter with a default-value to {{Documentation}} requires editing {{Documentation, template}} from

  {{ Documentation | heading=...}}

  to

  {{ Documentation | heading=...| new-parameter={{{new-parameter|default-value}}}}}

  then within {{Documentation}} new-parameter is always defined causing

  {{{new-parameter|default-value}}}

  to ignore default-value but with no ill effect.
• Maintaining new-parameter default value coherence requires

  {{ Documentation | heading=...| new-parameter={{{new-parameter|{{ Documentation/npdv }}}}}}}

  and within {{Documentation}}

  {{{new-parameter|{{ Documentation/npdv }}}}}

  adding 2 transcludes.
• See {{Documentation/docname}} and count how many times it's transcluded during one client transclude. The number may startle but IMO it's worthwhile keeping this one.

Please comment here

As the above may become documentation. – Conrad T. Pino 09:42, 16 November 2007 (UTC)

Option 1: redirect all

Redirect {{Template doc}} AND {{Documentation, template}} to {{Documentation}}.

Consequence: No default support for classic "(icon) Template documentation" heading.

Template documentation

Sample documentation.

Editors can experiment in this template's sandbox (create | mirror) and testcases (create) pages.
Subpages of this template.

Option 2: redirect one

Redirect {{Documentation, template}} to {{Template doc}}.

Revise {{Template doc}} to default to classic "(icon) Template documentation" heading.

Consequence: Costs avoided and Costs imposed move from {{Documentation, template}} to {{Template doc}}.

Template documentation

Sample documentation.

Editors can experiment in this template's sandbox (create | mirror) and testcases (create) pages.
Subpages of this template.

Option poll

• I like the classic look but considering Costs imposed and the icons and heading consensus, I support "Option 1: redirect all". – Conrad T. Pino (talk) 19:01, 18 November 2007 (UTC)

AzaToth supports "Option 2: redirect one" as evidenced by his {{Template doc}} revert with summary "(Reverted to revision 172237017 by ConradPino; it should still have the same look as the template it's deprecated against. using TW)" of my {{Template doc}} defaults to {{Documentation}} heading edit with summary "(let's find out who care's about classic heading: (icon) Template documentation)". – Conrad T. Pino (talk) 19:20, 18 November 2007 (UTC)

I suggest "Option 1: redirect all" for simplicity, but I also did like that template icon. Is it possible to adjust the display of the heading with a #switch, based on {{SUBJECTSPACE}} = "Template"? Or perhaps adding an optional "showicon" parameter? It's purely aesthetics, and not a vital feature of the template(s), but the icons did add some "friendliness" to the header.
I would also suggest moving the transclusion, sandbox & testcase lines up above the heading rule to as to not mix them in with the main documentation content. That's a separate issue, however. —Down10 ^TACO 00:38, 19 November 2007 (UTC)

All your icon suggestions are feasable but that's not the direction the Pretty icon eye candy discussion (above) is currently going. I suggest making an argument there and if so the poll becomes 2 and 2, far short of consensus. Please understand supporting "Option 1: redirect all" means no default icon unless an icon favoring "Pretty icon eye candy" consensus emerges. The present alternative is parameter heading which supports text, images or both and will be elaborated upon in the documentation. – Seperate issues warranting prior discussion will benefit if opened soon as seperate threads while the merging notice is drawing attention here. – Conrad T. Pino (talk) 09:33, 19 November 2007 (UTC)

I am in favor of Option 1: redirect all, for uniformity.--Patrick (talk) 01:19, 19 November 2007 (UTC)

I favour option 1 (redirect all) as well; these should be standardized. (I thought that was the whole point of all this ;) ). —{admin} Pathoschild 03:41:14, 19 November 2007 (UTC)

Your thought inspired reviewing the merge proposal discussion. Aesthetics, coding and standards, all there in general, little in specifics and nothing on the heading. Another lost opportunity, the Merge goals proposal by priority went unheeded. Pray tell me Sir, who shall save us from ourselves?!! :) Conrad T. Pino (talk) 09:33, 19 November 2007 (UTC)

{{Template doc inline}}'s final fate

It's officially retired per {{Template doc inline}} clients - completed above. {{Template doc inline/doc}} states the reasons {{Template doc inline}} can't be redirected. Comments regarding it's final fate are solicited. – Conrad T. Pino (talk) 09:02, 17 November 2007 (UTC)

Sorry, sometimes I'm slow. With no clients the behavior differences are moot. Redirection to discourge using the deprecated version is now an option. – Conrad T. Pino (talk) 09:06, 17 November 2007 (UTC)

After discussion with myself and finding consensus, this template was redirected to {{Documentation, template}}. – Conrad T. Pino (talk) 09:33, 17 November 2007 (UTC)

Spanish version

The Spanish version listed on the page right now is not useful at all. The Spanish equivalent of this template is called "Plantilla:Template doc". You can see it at es:Plantila:Template doc. Can somebody change this please? — Cuyler91093 - Contributions 09:40, 5 January 2008 (UTC)

Doc view and edit links

Could we remove the [view] link at the top of the page since it rather jars with the normal [edit] links and we have one bellow the header. And while we're at it rename [edit] when there's no page to [create] since it much more description about what's going on? —Dispenser (talk) 20:42, 17 January 2008 (UTC)

New parser

As a note, due to the new parser, there is no longer a benefit in placing template documentation on a subpage. Everything in <noinclude> is fully ignored. So the usage of this "system" is now purely cosmetic and easy of use, without technical benefit. A test like this will clearly show you this in the comments. --TheDJ (talk • contribs) 11:30, 30 January 2008 (UTC)

Actually it isn't, using this system still allows you to edit the documentation of a protected template and reduced server load as the pages transcluding the template wont be reparsed. — Dispenser 11:53, 30 January 2008 (UTC)

And it is nice to have a standardized way to do documentation. There are still a lot of lesser used templates where the documentation is on the talk page. --— Gadget850 (Ed) ^talk - 12:10, 30 January 2008 (UTC)

The ability to edit documentation without editprotected requests is the more important feature of the doc subpages. That reduces the admin workload greatly. On nonprotected templates you are correct that it makes less difference. — Carl (CBM · talk) 14:24, 30 January 2008 (UTC)

Merger

Hi,

The page Template:Usage of template (backlinks edit) fulfils the same role as this template, and content forking is discouraged. The aesthetics of {{Usage of template}} appeal to me more than this one; it would be nice if some elements could be incorporated into this template rather than the latter disappearing completely.

Thanks, Verisimilus T 17:40, 10 February 2008 (UTC)

It doesn't look so good with the monobook skin. I am guess your using the modern skin? If so you should go to MediaWiki:Modern.css and ask to add classes that will make {{documentation}} look better. —— Dispenser 19:54, 10 February 2008 (UTC)

Purge link

I'd like to see a purge link ([{{fullurl:{{ns:10}}:{{PAGENAME}}|action=purge}} purge]) for the template. I often edit templates and find that it's annoying to have to manually purge them. I'd like to suggest adding it as one of the first lines, eg.:

This documentation has been transcluded from ...

This page can be purged

-- SkyLined (talk) local time:01:50, 24 November 2024 (CET), server time: 17:29, 14 April 2008 (UTC)

Icon eye candy, again?

I just noticed that the eye candy and heading from the older template was added to this template today. That is, this image:

Currently when this template is used on template pages it shows the icon and has the heading "Template documentation". When shown on other pages it shows like it used to, no icon and the heading "Documentation". But this template is more or less only used for template documentation.

Such eye candy has been discussed on several talk pages, the latest round was above at section Pretty icon eye candy. I thought the consensus was that we should not use it. I think it just adds to the overall "information stress" of the design. And I liked the shorter title "Documentation". Simply using "Documentation" as heading also makes the code simpler since then we don't need the name space detection code that was added today.

--David Göthberg (talk) 21:56, 16 April 2008 (UTC)

Some technical details needed

I am making a wiki on MediaWiki, and would like to implement the Documentation class of templates. So, may I ask, what extensions and common.css classes are required for the proper functioning of these templates? Thanks!

Cheers,

--Samuel di Curtisi di Salvadori 02:59, 21 May 2008 (UTC)

Heading fix

{{AccessibilityDispute}}

{{Editprotected}}

The heading levels in the preload documentation subpage that this template (or probably one of its subtemplates) creates with the "create" button that appears in place of "edit" when the tag to which {{Documentation}} is applied has no /doc page yet, is using === Usage === and === See also === heading levels. These need to be changed to == Usage == and == See also ==, as many conscientious editors already do manually after creating of the preload /doc page (cf. Template:WPBannerMeta and many other examples), because it is semantically invalid XHTML to have h1 (the page title) followed by h3 with no intervening h2. I.e., it transgresses WP:ACCESSIBILITY. — SMcCandlish [talk] [cont] ‹(-¿-)› 18:18, 31 August 2008 (UTC)

Agree; per discussion. Andy Mabbett | Talk to Andy Mabbett 18:20, 31 August 2008 (UTC)

N Not done - This has been discussed a lot of times, in a lot of places. The green /doc boxes do have a h2 header, that is the "Template documentation" header at the very top of the green documentation box. Thus the headings inside the box should be h3 headers.

For some technical reasons the "Template documentation" header is not coded as a real h2 header. I didn't build this box but I think the reasons are something like this:

1: We want the table of contents inside the /doc box instead of before it, and we don't want the "Template documentation" header in the table of contents.

2: We want the edit button next to the "Template documentation" header to appear even if the template is protected.

All web browsers I have ever seen supports that heading levels are skipped over. And I have never heard that screen readers would have a problem with that. So I think you guys see a problem where there is no problem.

--David Göthberg (talk) 21:18, 31 August 2008 (UTC)

If it's not "coded as a real h2 header", then it's not an h2 header, it's just some prettified text. (For those interested, it's <span style="font-weight: bold; font-size: 125%;"><a href="/wiki/Image:Template-info.svg" class="image" title="Template-info.svg"><img alt="" src="http://upload.wikimedia.org/wikipedia/commons/thumb/4/4c/Template-info.svg/50px-Template-info.svg.png" border="0" height="26" width="50"></a> Template documentation</span>) The HTML is semantically broken. Whatever web browsers you - or anyone else - may have used does not change that fact. Andy Mabbett | Talk to Andy Mabbett 21:31, 31 August 2008 (UTC)

N Not done again. - For seeing readers of the template pages it is a h2 tag. If it bothers you that it is not an actual HTML h2 tag then what you need to do is to figure out a way to make that header an actual HTML h2 tag without breaking the documentation page's functionality.

And you should not use {{editprotected}} tags when you do not have consensus for an edit. It is not a debate tool.

--David Göthberg (talk) 22:28, 31 August 2008 (UTC)

For seeing readers of the template pages it is a h2 tag - No, it is not! And for blind users..? Or don't they count?

The edit above makes no reference to changing the line into a header; it does not need to be a header. The existing H3 headers need to be H2. Andy Mabbett | Talk to Andy Mabbett 00:20, 1 September 2008 (UTC)

Well, even according to the blind users that discuss in the accessibility project here at Wikipedia it is no problem if header levels are "skipped". As long as the essential headers on a page is within the h1-h3 range. So this is not at all an accessibility problem. Thus this is only about your syntax pedantry.

If syntax is so important to you, then I suggest you file a bugzilla request that they change back to how it once used to be: That MediaWiki does not interpret <h2> tags like == == tags. Then we can make the /doc page header an actual h2 tag and your syntax pedantry can be satisfied.

Besides, template space is the construction backyard of Wikipedia, you can't demand that a construction yard is 100% standards compliant and "accessible". Many template pages contain templates that are half. That is, there are two templates that work together and when just viewing one of them at a time you see "broken" HTML code. That we can never fix and have to live with, since template land is the construction backyard. The only thing that matters is that the finished building (the articles) are accessible. But again, skipping heading levels isn't even an accessibility issue.

And any changes to the /doc standard should be discussed at Wikipedia talk:Template documentation, not here. The preload page of this template only implements what is described over there.

--David Göthberg (talk) 10:36, 8 September 2008 (UTC)

Describing my and others' legitimate views on an accessibility matter as merely "syntax pedantry" is unacceptable; as is your removal of the dispute template while the dispute is ongoing. I have cited - in linked pages - accessibility guidelines and discussion. You merely claim the authority of uncited hearsay. I have placed a note linking to this discussion at Wikipedia talk:Template documentation.

It's notable also that this template's own documentation has had the header levels adjusted to the correct levels which we are requesting be used as default. Andy Mabbett (User:Pigsonthewing); Talk to Andy Mabbett; Andy Mabbett's contributions 11:00, 8 September 2008 (UTC)

Indeed. David, you appear to be ignoring, or confused about, the difference between headings, a semantic element type of [X]HTML on the one hand, and "stuff that looks like a heading to me" on the other. They are, as you must know deep down given your work on CSS elsewhere here, not the same. Whether they look the same to you is irrelevant. It's hard for me to be believe you are simply unaware of the semantic aspects of Web development, and only understand the presentation side of it, as if this were 1994. If that somehow is the case, well, that's okay – no one is demanding that you be a Web developer. However, please stop being obstructionist. Since you seem to be either willfully ignoring or not understanding the actual nature of the editprotecteds here and their simple and solid rationale, then just stop responding to them and go do something else and let some other admin who does care/understand deal with them.

Secondly, I don't see that anyone but you cares about the relative font size of the pseudo-heading used in the green box and that of the real headings inside it. If anyone were even noticing, they already would have complained about the display of the pseudo-heading itself, because...

Thirdly, the entire raison d'etre of this abuse of XHTML is absurd. The pretend-heading in the green box does not look like an h2 heading as you insist, but rather an h3. In order for the display to look the way you seem to think it should look, the /doc page headings would have to be h4! On top of that, it's presence inside a green "frame" makes it unlikely that anyone interprets it as anything like a h2 or h3 document heading, any more than they do the bold stuff in various warning templates; indeed, its very design rationale appears to be to ensure that this does not happen. Rather, it is obviously the caption or label of this transclusion "box", just like the one on {{todo}}, etc., and there is no WP-wide standard for such captions (unlike for actual headings), ergo no reader/editor expectations with regard to the caption's font size. If you really, really, really want want it to look like a fake heading (a bad idea), then make it look like h2 and put a class on it, and then do the rest properly: Get consensus for a new CSS class and related directive (I'll call it "foobarbaz" here):

	   #foobarbaz h2 { <CSS here to style it as if it were h3>; }
	   #foobarbaz h3 { <CSS here to style it as if it were h4>; } 
	   #foobarbaz h4 { <CSS here to style it as if it were h5>; } 
	   #foobarbaz h5 { <CSS here to style it as if it were h6>; } 
	   #foobarbaz h6 { <CSS here to style it as if it were normal-size bold text>; }

The sloppy, lazy way this is being done now is out-of-process, and without anything close to a good, encyclopedia-improving reason; it has not been consensus-vetted (and I'd bet real money it would not be, frankly) where consensus on styling of [X]HTML on Wikipedia is discussed. Given your level of participation there, you must surely understand that.

Fourthly, The fact that people who evidently either don't know what they are doing or talking about, or simply don't give a [censored] about standards compliance, have already had some discussions about this, and confused themselves into thinking they are doing something sensible, is neither here nor there. As a simple factual matter, this mangled markup is wrong. Period. Any page using it will not validate. Any strict parser that encounters it will choke.

Fifthly, it violates-in-spirit WP:MOS#Headings. While that technically applies strictly to articles, we all know full well that it is applied site-wide, from talk pages to guidelines.

PS: I change the bogus h3 back to an h2 every single time I encounter it deployed in "live" template documentation, and as far as I can tell I have never been reverted in doing so, not even once. Not even right here. NB: Short of a Centralized Discussion showing an overwhelming WP consensus in favor of violating the standards in this weird case just to get a visual effect of no consequence, I see no reason not to AWB them all into conformity with the specs. — SMcCandlish [talk] [cont] ‹(-¿-)› 10:43, 2 October 2008 (UTC)

PPS: I also object to the removal of the dispute tag. The multi-editor dispute is a fact, and no one editor is in a position to deny the existence of the dispute, especially when their response to solid reasons for the dispute, grounded in the HTML specs and over a decade of Web development best practices, basically amounts to "I don't see the difference." — SMcCandlish [talk] [cont] ‹(-¿-)› 10:53, 2 October 2008 (UTC)

PPPS: "As long as the essential headers on a page is within the h1-h3 range..." – they won't be. Since the documentation per se starts with h3, and a great number of templates have subsections in their "Usage" sections, many will end up as h4s. I wasn't aware of h4 being an accessibility problem to begin with, but if it is, you are making our own argument for us. — SMcCandlish [talk] [cont] ‹(-¿-)› 10:59, 2 October 2008 (UTC)

Does anybody other than Davidgothberg object to fixing this? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 09:27, 15 October 2008 (UTC)

I'm confused as to why this can't be switched from a <span> to a <h2> to satisfy everyone. In quick tests, it looks identical to the current header, but perhaps I'm missing something? --MZMcBride (talk) 19:51, 15 October 2008 (UTC)

MZMcBride: It was a long time since I tested that. But as far as I remember using a <h2> tag (which nowadays is parsed by MediaWiki the exact same way as a == == tag) has the following problems:

• The table of contents will end up above that heading. Which looks really weird in the green /doc box.
• There won't be an [edit] button for the documentation on templates that are protected. And on non-protected template pages the [edit] button will not go to the entire /doc page but only to section 1 if people do the mistake of using h2 headings further down in the /doc.
• And a minor thing that doesn't matter that much: The "Template documentation" header will show up in the TOC. And all the other headings will be indented one step in the TOC, if the other headings have the correct h3 level.

--David Göthberg (talk) 21:15, 15 October 2008 (UTC)

Can you give a diff showing these issues in effect? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 21:50, 15 October 2008 (UTC)

No? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 08:11, 17 October 2008 (UTC)

Ahh, you're correct David. Thanks for explaining. The ToC could probably be moved using __TOC__, but you won't have edit links when using <h2>. That's a symptom of the new preprocessor, as far as I'm aware. --MZMcBride (talk) 22:06, 15 October 2008 (UTC)

No-one? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 08:12, 17 October 2008 (UTC)

There are two major issues to keep in mind:

• this will break pages using the template in a section (see example); the "template documentation" text was intended as a box label rather than a distinct section header. This could be fixed by adjusting those pages and adding an optional header level parameter, but that seriously reduces simplicity of use.
• the table of contents will be placed inside the box directly above the header, which will look extremely odd. This cannot be fixed by using __TOC__, which will displace the regular TOC on pages with multiple sections before the template (see example).

—{admin} Pathoschild 09:59:46, 17 October 2008 (UTC)

I'd class those as minor, not major issues; documentation templates are not intended to be used in that way; in each of the example you gave, I've replaced them with links to the relevant template. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 14:43, 17 October 2008 (UTC)

I disagree, documentation templates are specifically intended for documentation. Changes which negatively impact ease-of-use and flexibility for little defined gain are not minor issues. Removing this useful template on any page that will break with your proposed changes is not an ideal solution; I see you have already been reverted by another user. —{admin} Pathoschild 22:16:03, 17 October 2008 (UTC)

...who did not understand the issue. Given that the current template is badly broken as described in detail above (and hence a fix would give us much more than "little defined gain"), what solution do you propose? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 22:29, 17 October 2008 (UTC)

The template is not broken; the box label is not a section header. We can fix the h1->h3 jump simply by changing the default header levels in Template:Documentation/preload to h2. This was the original proposal, and I see no problem with doing so. —{admin} Pathoschild 22:46:19, 17 October 2008 (UTC)

The "fix" to which you refer is to mend the situation which I refer to as "broken"; I'm glad that you support my proposal to apply it. Thank you. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 10:07, 18 October 2008 (UTC)

Pathoschild: If you increase the heading level inside the /doc pages to h2 then you will break the pages that use a /doc box inside a section, like the examples you linked to. Since then the headings inside the /doc box will have the same heading level as the surrounding section.

The documentation system was designed in such a way that the same /doc page can be used both on a template page and on other pages. Having a jump between h1 -> h3 is not a problem for any known browsers and likely will never be a problem, since it for practical reasons are in so common use. Also as I have stated before, the blind that use screen readers have no problem with it, since screen readers handle it fine. So increasing the level to h2 in the /doc pages will break things, just to try to "solve" a non-existing problem.

--David Göthberg (talk) 11:23, 18 October 2008 (UTC)

The problem has been well-documented, both above and at Wikipedia talk:Accessibility#Headings in page template. Yours appears to be the only dissenting voice. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 11:35, 18 October 2008 (UTC)

Davidgothberg: No, changing the default level won't affect any existing documentation pages. If someone wants to use a documentation page in a section, they can easily adjust the headers on that page. The only change would be with the preload template, which is the text that gets filled in automatically in the edit box when creating a new documentation page. —{admin} Pathoschild 19:13:54, 18 October 2008 (UTC)

Pathoschild: Then you have not understood the examples you yourself linked to. The same /doc page is often used both on the template page and in a section on for instance a WikiProject page. Thus such a /doc page can not have h2 tags, since that looks very weird in the table of contents on the WikiProject page. And it would give the wrong heading levels on those WikiProject pages in a way that I think actually would be disturbing for both the blind and the seeing users. So using h3 tags in the /doc pages is the solution that works everywhere for everyone.

--David Göthberg (talk) 11:56, 20 October 2008 (UTC)

Using h3 tags in /doc pages in this way does not work "everywhere for everyone", as has already been explained to you, at length, more than once. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 12:26, 20 October 2008 (UTC)

David Göthberg: I think you misunderstand what the preload template does. It has no effect whatsoever on existing pages, and does not enforce particular header levels. No matter of what the initial text is, you can change to level five (or to a big happy smile) if you want. —{admin} Pathoschild 17:23:32, 20 October 2008 (UTC)

Pathoschild: I know perfectly well how preload pages work. And I think that you are very well aware of that people usually use the code as is from the preload pages, since otherwise you wouldn't be so keen on changing the preload page. And when a user makes a template /doc page he can not know if people later will use that /doc page also at other places. You mean people should have to fix the /doc pages before they also can use them on other pages?

--David Göthberg (talk) 19:00, 20 October 2008 (UTC)

Sure; it would be the work of moments in the rare cases it is needed. That said, I don't care whether or not my proposed solution is implemented (so long as the previous proposals that would break the template are not implemented). —{admin} Pathoschild 18:54:54, 21 October 2008 (UTC)