Page MenuHomePhabricator

Support a given subpage as the "official" documentation subpage for templates, to avoid duplicate TemplateData
Closed, ResolvedPublic1 Estimated Story Points

Description

My wiki users are confused about adding TemplateData. We use the Wikipedia {{documentation}} template. My users often add <templatedata> to both the template itself and the /doc subpage, without meaning to, because the "Manage TemplateData" button appears on both. I know you display a warning about it on the template page, but it would be better if the button appeared on only one of the pages. So here is a suggested solution.

Please allow a wiki to officially designate a particular subpage for template documentation. For example:

//LocalSettings.php:
$wgTemplateDataSubpage = "doc";

If this variable is set, then the "Manage TemplateData" button would appear only when editing the /doc subpage, not when editing the template itself. This prevents users from writing redundant <templatedata> blocks on the template + the subpage.

I suspect you can dream up other interesting applications, if the wiki has a known standard subpage for docs.

Event Timeline

maiden_taiwan raised the priority of this task from to Needs Triage.
maiden_taiwan updated the task description. (Show Details)
maiden_taiwan added a project: TemplateData.

This approach might solve the problem that you've noted in modules/ext.templateDataGenerator.ui.js:

// Check if there's already a templatedata in a related page
// TODO: Hard-coding 'doc' is dangerous for i18n. We need to find 
// a better way to define 'related' pages for a template.

This approach might also solve a quirk in VisualEditor. Suppose you document Template:Foo by placing TemplateData into Template:Foo/doc. Now go to VisualEditor and use the Insert/Template menu item and type "Foo". Through autocompletion, you get both Foo and Foo/doc as possible completions, both with the same TemplateData description showing up, which is pointless because nobody's ever going to want to transclude Template:Foo/doc into an article. If the wiki had a designated subpage like "doc" for TemplateData, then VisualEditor could filter the list of templates to exclude those subpages from the autocompletion list.

The plan is to move TemplateData out from being a parser tag into being its own content type, either as a parallel content stream (blocked on T107595: [RFC] Multi-Content Revisions) or as an associated Template_data: page (blocked on T487: RfC: Associated namespaces). We could do this as a quick hack in the mean time, but it'd be pretty unsatisfactory. :-(

Jdforrester-WMF moved this task from To Triage to Freezer on the VisualEditor board.

Interesting. Will there be a migration script of some kind to move templatedata from its current format into the new one?

Interesting. Will there be a migration script of some kind to move templatedata from its current format into the new one?

Yes, the migration is definitely going to need a maintenance script for WMF production if no-where else.

quoting from description,
"I know you display a warning about it on the template page" - which kind of warning is that, a software message? I can't see any and I just got this problem reported on it.wp as well.

If you have the TemplateData extension installed, and you have docs on page Template:Foo/doc, and you edit Template:Foo, you'll see a note near the button for editing template data, saying that the doc subpage already has templatedata on it.

I can see a yellow banner at the English Wikipedia, not on the French or Italian one.

I can see a yellow banner at the English Wikipedia, not on the French or Italian one.

There is no banner on the latter two because those pages actually don't have a /doc sub page.

The {{Documentation}} template used on the French Wikipedia at "Modèle:Article" includes from /Documentation instead. (Modèle:Article/Documentation)

Italian Wikipedia uses a {{Man}} template on "Template:Cita_news" which includes /man (Template:Cita_news/man), and yet another template that separately includes a /TemplateData sub page.

Change 411225 had a related patch set uploaded (by Esanders; owner: Esanders):
[mediawiki/extensions/TemplateData@master] Make '/doc' subpage an MW message for local overrides

https://gerrit.wikimedia.org/r/411225

The above patch allows a message to be set to override the default 'doc'. Looking at the top Wikipedias the following messages should be set:

https://fr.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Documentation
https://de.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Doku
https://sv.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Dok
https://it.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - man TemplateData
https://pl.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - opis

Others appear to just use 'doc' (es,pt, ru, ja, zh)

I would just disallow the possibility to add another TD if one detected in the template directly or in the template docpage already.

(offtopic @Esanders: You listed doc subpage names for some wikis above. Do you think you could help with https://phabricator.wikimedia.org/diffusion/PWBC/browse/master/pywikibot/families/wikipedia_family.py$172 and list somewhere all the doc subpage names on all Wikipedias? I would submit the patch to pwb, I just don't know how to get list of those.)

I just looked on wiki, mostly by looking at the citation templates, e.g. Template:Cite book

Change 411225 merged by jenkins-bot:
[mediawiki/extensions/TemplateData@master] Make '/doc' subpage an MW message for local overrides

https://gerrit.wikimedia.org/r/411225

Deskana set the point value for this task to 1.

The following values have been set:
https://fr.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Documentation
https://de.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Doku
https://sv.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - dok
https://it.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - TemplateData
https://pl.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - opis
https://bs.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - dok
https://ca.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - ús
https://dsb.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Dokumentacija
https://fa.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - توضیحات
https://fi.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - ohje
https://hsb.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Dokumentacija
https://ka.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - ინფო
https://ko.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - 설명문서
https://no.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - dok
https://nn.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - dok
https://sk.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Dokumentácia
https://sr.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - док
https://uk.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - Документація
https://ur.wikipedia.org/wiki/MediaWiki:Templatedata-doc-subpage - دستاویز

cswiki should be doc, but in that system message it is correct

So, I came here from https://sv.wikipedia.org/w/index.php?oldid=42703510. Now, I don't understand the VE or TemplateData stuff, but I do know what doc pages are. Is the purpose of this task to determine what doc pages usually are called on different projects? In that case, you must have gotten it wrong, at least for svwiki. https://sv.wikipedia.org/w/index.php?search=intitle%3A%2F%5C%2Fdok%2F&ns10=1 shows that there are 2 097 pages in the Template namespace where the title matches the regular expression /\/dok/. The same search with a capital D (https://sv.wikipedia.org/w/index.php?search=intitle%3A%2F%5C%2FDok%2F&ns10=1) shows 4 pages.

This list is somewhat broken for all languages

cswiki should be doc, but in that system message it is correct

Should've been bswiki

In that case, you must have gotten it wrong, at least for svwiki.

Thanks, have updated the list.

Is the purpose of this task to determine what doc pages usually are called on different projects?

Essentially, yes. More specifically the subpage where the templatedata is written, which is usually the same thing (although not always, see itwiki).