This page is for me to construct a lofty proposal about templates and their documentation. Comments are welcome! Please be as critical as possible.
There are two fundamental components of a Wikipedia article:
This pattern applies to most namespaces. But for a Wikipedia template, there are instead three (sometimes five) fundamental components:
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.
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 | ||
---|---|---|---|---|
|
| |||
... to call a template | {{ Foo}} (unchanged) | |||
... to display documentation on an expected page e.g. Template:Foo or Module:Foo |
|
| ||
... to display documentation on an unexpected page e.g. userpages | <noinclude>{{Documentation}}</noinclude> coupled with User:Foo/doc or content= parameter
|
| ||
... to categorize a page on which a template is transcluded |
|
| ||
... to categorize a template itself, or a Module, or any namespace in which documentation expected |
|
| ||
... to categorize a User: or Wikipedia: page with documentation, or any namespace in which documentation not expected | <noinclude>[[Category:Foo]]</noinclude>
|
| ||
... two templates, one documentation page |
|
| ||
... 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 |
|
I believe there are many benefits to this plan. By creating a strong distinction between template code and template documentation, we enable:
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.
I believe the implementation could be done step by step, as follows. If there are any issues please let me know.
{{#Documentation}}
parser function. This will function identically to {{
Documentation}}, however it will not be transcluded when a page is transcluded.
{{#Documentation}}
{{#Documentation}}
(or by {{
Documentation}}, which merely calls the former anyway)
{{#Documentation}}
transcludes Documentation:Foo if it exists then stops (only transcluding /doc if Documentation: fails)<noinclude>[[Category:Foo]]</noinclude>
in templates' code
[[Category:Foo]]
in a template's code does not affect the template itself, only pages on which it is transcluded.
[[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)
This page is for me to construct a lofty proposal about templates and their documentation. Comments are welcome! Please be as critical as possible.
There are two fundamental components of a Wikipedia article:
This pattern applies to most namespaces. But for a Wikipedia template, there are instead three (sometimes five) fundamental components:
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.
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 | ||
---|---|---|---|---|
|
| |||
... to call a template | {{ Foo}} (unchanged) | |||
... to display documentation on an expected page e.g. Template:Foo or Module:Foo |
|
| ||
... to display documentation on an unexpected page e.g. userpages | <noinclude>{{Documentation}}</noinclude> coupled with User:Foo/doc or content= parameter
|
| ||
... to categorize a page on which a template is transcluded |
|
| ||
... to categorize a template itself, or a Module, or any namespace in which documentation expected |
|
| ||
... to categorize a User: or Wikipedia: page with documentation, or any namespace in which documentation not expected | <noinclude>[[Category:Foo]]</noinclude>
|
| ||
... two templates, one documentation page |
|
| ||
... 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 |
|
I believe there are many benefits to this plan. By creating a strong distinction between template code and template documentation, we enable:
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.
I believe the implementation could be done step by step, as follows. If there are any issues please let me know.
{{#Documentation}}
parser function. This will function identically to {{
Documentation}}, however it will not be transcluded when a page is transcluded.
{{#Documentation}}
{{#Documentation}}
(or by {{
Documentation}}, which merely calls the former anyway)
{{#Documentation}}
transcludes Documentation:Foo if it exists then stops (only transcluding /doc if Documentation: fails)<noinclude>[[Category:Foo]]</noinclude>
in templates' code
[[Category:Foo]]
in a template's code does not affect the template itself, only pages on which it is transcluded.
[[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)