Suggested possible ways forward:

• Exclude all subpages except those explicitly marked as templates, e.g by magic word or category
• Include all subpages except those explicitly marked as not being templates, e.g. by magic word or category

Neither of these options are imho maintainable or author-friendly. Alternative ideas (from T98562).

• Filter out /doc (hardcoded).
  • Principally not as ugly as one might think, since TemplateData does this as well. Though TemplateData only uses that hardcoded value to discover related pages in the graphical interface. It is in no way enforced server-side or encouraged in its interface when inserting/editing template data.
  • We'd have to filter it client-side, which means the number of results shown is inconsistent. To avoid false positives with template names that actually end in "/doc", we'd only remove results if the other title is also in the list. (E.g. "Template:Dac/duc/doc" or something like that.)
• Filter out results that are transcluded in other results.
  • Requires an additional query somewhere, but might be a smart way to do it. We'd only omit results that are transcluded by others. So "Template:Foo/doc" would be omitted because according to the link tables, "Template:Foo" (also in the suggestions) transcludes "Template:Foo/doc". This doesn't work well because documentation pages themselves often make use of various other templates. So any template used in the preview, examples, or documentation would never show up in the suggestions.
• Filter out results that transclude template data.
  • Not sure how this would work, but since the same duplication is also present in the page-property index (which is where template data is stored), we can detect that Foo and Foo/doc both have (the same) template data. We may be able to de-duplicate results that way (and pick the one that sorts higher, or the one with a shorter name, aka not the helper page that tends to be a sub page).

And of course T56140: Move TemplateData to its own JSON-content namespace and associate with Template-namespace, or to its own TemplateData content model and revision slot – which I'd say is the ideal solution. And is quite feasible to implement.

I think we have simple way to filter out subpages of templates.

Another option: instead of filtering, use sorting by usage (group by on templatelinks) instead of alphabetic sorting.

Suggestion: allow the wiki administrator to designate a particular subpage string, such as doc, as the official place to keep TemplateData. Then VisualEditor can intelligently and unambiguously filter these pages out. See T125222.

In T54448#1991488, @maiden_taiwan wrote:

Suggestion: allow the wiki administrator to designate a particular subpage string, such as doc, as the official place to keep TemplateData. Then VisualEditor can intelligently and unambiguously filter these pages out. See T125222.

This one could work! On pt-wiki we use "doc" as the documentation subpage and "dados" as the TemplateData. Maybe blacklisting both of them could help VisualEditor interpreting them as not templates to be transcluded.
I don't think that "excluding all subpages except those explicitly marked as templates" would be a good idea, because there are plenty of templates (Info/Patologia, Info/Grupo étnico, Info/Facção de conflito etc.) located on subpages.

An example: I accidentally {{Nemzetközi katalógusok/doc}} instead of {{Nemzetközi katalógusok}}, because I was not thoughtful enough. We should find a way to avoid the problem.

In T54448#1991488, @maiden_taiwan wrote:

Suggestion: allow the wiki administrator to designate a particular subpage string, such as doc, as the official place to keep TemplateData. Then VisualEditor can intelligently and unambiguously filter these pages out. See T125222.

(This is an old comment but I think it would be helpful.) TemplateData already has a message for this in the configuration, MediaWiki:Templatedata-doc-subpage, so implementing solutions based on that shouldn’t be a problem.

Change 464718 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/extensions/TemplateData@master] Don't store templatedata pageprop on doc-subpage

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

Change 464718 merged by jenkins-bot:
[mediawiki/extensions/TemplateData@master] Don't store templatedata pageprop on doc-subpage

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

Change 483205 had a related patch set uploaded (by Jforrester; owner: Jforrester):
[mediawiki/extensions/VisualEditor@master] MWTemplateTitleInputWidget: Filter out templates named '…/doc'

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

@Jdforrester-WMF, how this would be deployed? How your change will identify language variants for /doc?

In T54448#4876695, @Trizek-WMF wrote:

@Jdforrester-WMF, how this would be deployed? How your change will identify language variants for /doc?

It'd be a train patch. Communities already (can) define the template documentation sub-page for the TemplateData extension via the templatedata-doc-subpage message, and this just re-uses that, which defaults to foo (so if you create Template:Foo/doc it'll be hidden, but Template:Foo/I have another sub-page to be confusing won't). Not merged yet though. I don't think this'd be worth a Tech News post.

Thanks!
I think it worth a Tech News post since some communities may see the difference. It is a good opportunity to highlight templatedata-doc-subpage too is not already known.

Is this done and will be deployed next week? (It's been added to Tech News.) I can't see that in the task, but I could be missing something?

In T54448#4888682, @Johan wrote:

Is this done and will be deployed next week? (It's been added to Tech News.) I can't see that in the task, but I could be missing something?

Nope, sorry, code still going through review. I'll go poke it now.

Change 483205 merged by jenkins-bot:
[mediawiki/extensions/VisualEditor@master] MWTemplateTitleInputWidget: Filter out templates named '…/doc'

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