User blog:Thisismyrofl/Suggestion: "Documentation" namespace


 * 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: This pattern applies to most namespaces. But for a template, there are instead three fundamental components: 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.
 * content page, and a
 * talk page for discussion.
 * 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

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.

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
 * 1) Create a   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
 * 1) Remove the need for Documentation in those namespaces: make transclusion automatic if not already done by   (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.
 * 1) 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  transcludes Documentation:Foo if it exists then stops (only transcluding /doc if Documentation: fails)
 * 1) Change all instances of   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
 * 1) Code Mediawiki such that bare   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
 * 1) Code Mediawiki such that bare   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
 * 1) Code a Special:UndocumentedPages and any other extra bonuses to be had