Suggestion: "Documentation" namespace

Other blogs by Thisismyrofl Infoboxes Infoboxes old and new Creating a new-style infobox Customizing a new-style infobox Creating a new-style infobox outdated Customizing a new-style infobox outdated Suggestions "Documentation" namespace New usergroup "Rollback-global" Chat PM visibility (With working CSS!) "Your Wiki"

This proposal is adapted from my similar proposal at Wikipedia.

I want to suggest a new namespace for use on Wikias. The new namespace would be called "Documentation".

The issue

There are two fundamental components of an article:

• content page, and a
• talk page for discussion.

This pattern applies to most namespaces. But for a template, there are instead three 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

Somewhere in the development of wikis, 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	Template:Foo used for template code Documentation:Template:Foo used for documentation Documentation expected in Template:, but not in other namespaces Documentation automatically transcluded without wiki markup in this expected namespace 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	<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	<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: page with documentation, or any namespace in which documentation not expected	<noinclude>[[Category:Foo]]</noinclude>	[[Category:Foo]] on documentation [[Category:Foo]] on User: page, if not intended to be transcluded
... two templates, one documentation page	Soft redirect as first parameter of {{Documentation}}	Soft redirect (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 User: 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.

1. Declare certain namespaces as "expecting documentation": namely, Template:, but not ones like User:

   These are namespaces whose content typically will not require documentation separate from the page itself

2. 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}}

3. 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)

   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 may use documentation but do not expect documentation; the {{Documentation}} must stay, in those instances.

4. 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)

5. 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

6. 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

7. 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

8. Code a Special:UndocumentedPages and any other extra bonuses to be had