User:Thisismyrofl/Templates proposal

This page is for me to construct a lofty proposal about templates and their documentation. Comments are welcome! Please be as critical as possible.

The issue

There are two fundamental components of a Wikipedia article:

content page, and a
talk page for discussion.

This pattern applies to most namespaces. But for a Wikipedia template, there are instead three (sometimes five) fundamental components:

template code, which is the actual wikitext and parameters, etc, to be transcluded into any number of articles
template documentation, which describes the template, why it's needed, how to use it
the talk page for discussion
occasionally, sandbox and testcases pages, the location of which I do not object to

Somewhere in the development of this encyclopedia, these three unique components have been squished into space for two components: the code-and-documentation, and the talk page. The template documentation is not given much of any actual accommodation in the Mediawiki software, instead being treated as just another template (a template that in reality will be transcluded into exactly one page). To accommodate this double function of the Template: namespace, we use lots and lots of nasty include rules: noinclude, onlyinclude, includeonly. This category applies to the host page, this category to the template itself. Virtually every major template has documentation, but still we don't think it's ubiquitous enough for an implementation more universal than pasting {{Documentation}} and include rules on every template page.

The proposal

I propose a new system.

Gray text implies something that will be considered less than ideal, but still works.

~~Crossed out text implies something that will be broken and needs to be changed.~~

I want...	Current system	My plan
	Template:Foo used for template code Template:Foo/doc used for documentation Module:Foo/doc used for documentation Wikipedia:Foo/doc used for documentation	Template:Foo used for template code Documentation:Template:Foo used for documentation Documentation:Module:Foo used for documentation Documentation:Wikipedia:Foo used for documentation Documentation expected in Template: and Module:, but not in Wikipedia: or User: Documentation automatically transcluded without wiki markup in these expected namespaces Categories in template code apply only to the host pages, not the template itself, no include rules Categories in a page's documentation apply only to the corresponding page, no include rules `{{#Documentation}}` parser function created, mostly identical in function to {{Documentation}} `{{#Documentation}}` and auto transclusion check for Documentation:Foo; failing that, they check Foo/doc {{Documentation}} changed to refer directly to `{{#Documentation}}` Special:WithoutDocumentation page created
... to call a template	{{Foo}} (unchanged)
... to display documentation on an expected page e.g. Template:Foo or Module:Foo	`<noinclude>{{Documentation}}</noinclude>` coupled with Template:Foo/doc or `content=` parameter	automatic coupled with Documentation:Template:Foo or with Template:Foo/doc `{{#Documentation}}` coupled with `content=` parameter, Documentation:Template:Foo, or with Template:Foo/doc `{{Documentation}}` coupled with `content=` parameter, Documentation:Template:Foo, or with Template:Foo/doc `<noinclude>{{Documentation}}</noinclude>` coupled with `content=` parameter, Template:Foo/doc (unchanged) or with Documentation:Template:Foo
... to display documentation on an unexpected page e.g. userpages	`<noinclude>{{Documentation}}</noinclude>` coupled with User:Foo/doc or `content=` parameter	`{{#Documentation}}` coupled with `content=` parameter, Documentation:Template:Foo, or with Template:Foo/doc `{{Documentation}}` coupled with `content=` parameter, Documentation:Template:Foo, or with Template:Foo/doc `<noinclude>{{Documentation}}</noinclude>` coupled with `content=` parameter, Template:Foo/doc (unchanged) or with Documentation:Template:Foo
... to categorize a page on which a template is transcluded	`<includeonly>[[Category:Foo]]</includeonly>`	`[[Category:Foo]]` on template code `<includeonly>[[Category:Foo]]</includeonly>` (unchanged)
... to categorize a template itself, or a Module, or any namespace in which documentation expected	`<includeonly>[[Category:Foo]]</includeonly>` on template documentation `<noinclude>[[Category:Foo]]</noinclude>` on template	`[[Category:Foo]]` on template documentation `<includeonly>[[Category:Foo]]</includeonly>` on template documentation (unchanged) ~~`<noinclude>[[Category:Foo]]</noinclude>` on template~~ won't work
... to categorize a User: or Wikipedia: page with documentation, or any namespace in which documentation not expected	`<noinclude>[[Category:Foo]]</noinclude>`	`[[Category:Foo]]` on documentation `[[Category:Foo]]` on User: or Wikipedia: page, if not intended to be transcluded
... two templates, one documentation page	Soft redirect as in {{Wrap}} first parameter of {{Documentation}}	Soft redirect as in {{Wrap}} (unchanged) first parameter of `{{#Documentation}}` first parameter of {{Documentation}} (unchanged) hard redirect of documentation pages
... a list of templates without documentation	I'm out of luck	`[[Special:UndocumentedPages]]`
... to mark a page that expects documentation as needing documentation	The only indication is a blank space where the documentation would be	Template: pages automatically display warnings if documentation lacking Module: pages automatically display warnings if documentation lacking Wikipedia: pages have no indication, because documentation not expected

The benefits

I believe there are many benefits to this plan. By creating a strong distinction between template code and template documentation, we enable:

automatic documentation transclusion, without {{Documentation}}
intelligent category application to host pages, and templates themselves, without include rules
Better analysis of page statistics by Special pages.

Mediawiki support for such a system would also be good for smaller wikis, who will be able to create templates with less confusing code.

I have provided below a plan for enacting my system.

The implementation

I believe the implementation could be done step by step, as follows. If there are any issues please let me know.

Declare certain namespaces as "expecting documentation": namely, Template: and Module:, but not ones like User: or Wikipedia:
These are namespaces whose content typically will not require documentation separate from the page itself
Create a {{#Documentation}} parser function. This will function identically to {{Documentation}}, however it will not be transcluded when a page is transcluded.
Now you can change {{Documentation}} to directly refer to and transfer any parameters to {{#Documentation}}
Remove the need for {{Documentation}} in those namespaces: make transclusion automatic if not already done by {{#Documentation}} (or by {{Documentation}}, which merely calls the former anyway)
This would be similar to how citations are added automatically if not by being called.

The automatic system could produce a warning in those namespaces if no documentation is provided, along with an invitation to create the documentation.

Having deprecated {{Documentation}} you can begin to remove it in its uses unless needed. A bot might be useful in incontrovertible cases. There doesn't seem to be any need to hurry, though.

Namespaces such as User: and Wikipedia: may use documentation but do not expect documentation; the {{Documentation}} must stay, in those instances.
Add a Documentation: namespace
{{Documentation}} and the automatic documentation transclusion system can transclude Documentation:Foo; failing that, they can transclude instead Template:Foo/doc.

Now you can begin leisurely moving your documentation pages from Foo/doc to Documentaton:Foo, perhaps by a bot.

There is no need to worry about redirects left at the /doc subpage, because {{#Documentation}} transcludes Documentation:Foo if it exists then stops (only transcluding /doc if Documentation: fails)
Change all instances of <noinclude>[[Category:Foo]]</noinclude> in templates' code
Any categories on template pages intended to categorize the templates themselves will be broken by the next step. So this step is urgent! A bot will be needed.

This is the only step I can think of that really would break other things if not completely done in time
Code Mediawiki such that bare [[Category:Foo]] in a template's code does not affect the template itself, only pages on which it is transcluded.
Now you can begin leisurely removing incontrovertible includeonly rules, perhaps by a bot
Code Mediawiki such that bare [[Category:Foo]] in a Documentation: page's code does not affect the documentation itself, only the template with which it is aligned (and not any pages on which the template is used)
Now you can begin leisurely removing incontrovertible includeonly rules, perhaps by a bot
Code a Special:UndocumentedPages and any other extra bonuses to be had