Wikipedia talk:Template documentation

discussion at Template talk:High-use

Please see Template talk:High-use § Different wording?.

—Trappist the monk (talk) 14:43, 24 November 2022 (UTC)

Heading level: 2 or 3?

I see a lot of templates that use level-3 headings in the documentation, rather than the normal level-2. Is this an established/documented best practice, or did people just start doing it since it looked nice? {{u|Sdkb}} ^talk 19:05, 22 July 2023 (UTC)

Which ones? The most commonly used templates like {{cite web}} use the normal level 2 headings, and I imagine they have the most eyes on them. Rjjiii (talk) 19:34, 22 July 2023 (UTC)

@Sdkb: It's not a crime to use level 3 headings in doc pages, provided that there is at least one level 2 heading earlier on. However, if the first heading that you see is level 3, this does cause an accessibility issue, and I normally only see these on older doc pages. Newer ones, created in the last eleven or so years (since this edit) using the "create" link on a template that uses {{documentation}} with no parameters and which had no existing /doc subpage, will open an edit window preloaded from Template:Documentation/preload which has a level 2 heading for the Usage section, and if this is left alone, all manually-added level 3 headings added after that will be valid.

That said, some years ago (I'm guessing 5-10 years back), there were editors who on finding a doc page that began with a level 3 heading, would raise the level of that and all other headings (3→2, 4→3, etc.) to fix the accessibility issue, and within a day somebody else would revert on the grounds of "it looked alright to me". Some people can be kinda touchy when an edit is made solely for accessibility reasons. --Redrose64 🌹 (talk) 19:48, 22 July 2023 (UTC)

Ah, thanks for providing the history there (and thanks to 2011-era SMcCandlish) for the fix)! Given that, it seems that using level-2 is the correct approach. Is there a reason that the "Template documentation" text at {{documentation}} seems to use level-3? That might be part of what's causing the confusion. {{u|Sdkb}} ^talk 20:34, 22 July 2023 (UTC)

Looks like something to fix. I would guess it's buried somewhere in Module:Documentation or a subpage thereof.  — SMcCandlish ☏ ¢ 😼  21:19, 22 July 2023 (UTC)

@SMcCandlish, around line 550, perhaps? {{u|Sdkb}} ^talk 21:26, 22 July 2023 (UTC)

Messing with Lua stuff gives me fits. I'll let someone more competent with that language try to adjust it.  — SMcCandlish ☏ ¢ 😼  21:31, 22 July 2023 (UTC)

It's not a heading at all, just normal text dressed up with some CSS. Omitting the image and the view/edit/etc. links, the HTML is:

<div class="documentation-startbox"><span class="documentation-heading" id="documentation-heading">Template documentation</span></div>

so it has no "level" as such. The stylesheet that picks up those two classes is at Module:Documentation/styles.css. The effect of the two together is

Template documentation

which isn't a heading. --Redrose64 🌹 (talk) 21:39, 22 July 2023 (UTC)

@Redrose64, hmm, interesting. Should the size perhaps be increased to align with level-2, in that case? Where would that be done? {{u|Sdkb}} ^talk 21:41, 22 July 2023 (UTC)

The appearance may be changed in the stylesheet, but that won't make any difference to the accessibility issue if the first heading is a level 3 heading. --Redrose64 🌹 (talk) 21:44, 22 July 2023 (UTC)

The idea is that people will be less likely to use level-3 headers if the "Template documentation" line isn't smaller than the section headers, which looks weird/doesn't create a good visual hierachy. {{u|Sdkb}} ^talk 21:51, 22 July 2023 (UTC)

As editing a documentation page brings you to the standalone page, you don't see the "Template documentation" text when previewing the page, so I don't think changing its size will make much difference. isaacl (talk) 05:42, 28 July 2023 (UTC)

People still remember, though. I think seeing that the label appears heading-3-sized makes people want the headings within to be that size or smaller. And really, the impulse isn't totally wrong — good visual hierarchy dictates that more core-esque elements should be bigger, as we want people to read/understand that the green box is documentation before we want them to check out what's in it. So again, I'm wondering which place would be edited. {{u|Sdkb}} ^talk 12:22, 28 July 2023 (UTC)

Module:Documentation/styles.css is where you can change sizing etc. Do note, however, that headings aren't the same in all skins. What is one size in Vector 22 is different in Minerva, Timeless, and so on. Izno (talk) 02:24, 29 July 2023 (UTC)

Indeed, the template does not output a heading on this point. There's a couple reasons why. The first is to dodge becoming part of the table of contents, which would be the solitary level 2 "Template documentation", and the multitude of level 3 headings. Which is the second reason it doesn't: the documentation heading didn't want to take a stance on which was more correct.

"Template documentation" probably should be a heading, but that "don't want it to be part of the table of contents" kind of dooms that. Izno (talk) 23:07, 25 July 2023 (UTC)

Though of course that just raises the question "Why would we not want it part of the ToC?"  — SMcCandlish ☏ ¢ 😼  06:08, 28 July 2023 (UTC)

It ends up being the only H2, since everything else below it is semantically part of the documentation and so should have H3s or lower. Which makes your TOC look really silly. Izno (talk) 02:21, 29 July 2023 (UTC)

Relevant BRFA

 You are invited to join the discussion at Wikipedia:Bots/Requests for approval/SdkbBot 4. {{u|Sdkb}} ^talk 05:10, 2 August 2023 (UTC)

When to use?

I could not find a clear answer to a question I had. When to use a /doc subpage instead of having the documentation right in the template page inside noinclude tags? One case I can think of is if the documentation is to be reused for other templates. Are there any others? -Klamactocrat (talk) 14:18, 4 March 2024 (UTC)

The only time I would consider not using a /doc subpage is if the template could be unambiguously documented in a single sentence. That means no parameters, no tricky behavior, no similar templates that might be alternatively used or used in conjunction with your template. Given that even the simplest of templates almost always have related templates to reference in the documentation, it's pretty much universal to use a /doc subpage. VanIsaac, GHTV ^cont_WpWS 16:53, 4 March 2024 (UTC)

I was trying to even come up with an example template, and realized I'd actually created one! See {{I-}} for an example of a template that not only doesn't have /doc subpage, but doesn't really have any reason to. VanIsaac, GHTV ^cont_WpWS 20:29, 4 March 2024 (UTC)

@Klamactocrat: The primary reason for having the doc on a separate page is to permit it to remain unprotected (and therefore editable by all) when it is felt necessary for the template code to remain static, which requires some level of protection. Two pages allows for two independent prot settings. --Redrose64 🌹 (talk) 09:17, 5 March 2024 (UTC)

Navboxes like {{Australian Individual Speedway Championship}} and other templates with standardized documentation like {{Lang-es}} often do not have /doc subpages. – Jonesey95 (talk) 19:23, 5 March 2024 (UTC)