User blog:Thisismyrofl/Suggestion: "Template documentation" namespace

I've been thinking about the way that template documentation is managed with Mediawiki, the software used by all Wikia wikis as well as by Wikipedia.

Most wikis worth their salt make an attempt to write documentation for their templates, so that future users attempting to work with the (sometimes very complicated) templates can readily make use of them. Inevitably, this results in a jumble of the source code, something like this:

For such a ubiquitous system, it's quite complicated, init? And it only serves to make the writing of documentation quite tedious, so that many people go without writing documentation in the first place. To mitigate this, I'd recommend a new namespace just for template documentation, as well as a few changes to the current Template namespace.

How would it work? First, let's consider the current Template namespace.

Template: namespace (current)

 * Documentation: Not applied by default, only added when a Documentation is added to the end of the Template page.
 * Documentation traditionally stored at Template: /doc
 * An unintuitive, unclean-looking page title, isn't it?
 * Serves to fill up Special:Allpages very easily with documentation pages. See Wikipedia's Allpages.
 * Also serves to fill Special:WantedTemplates very easily with documentation pages. Check out c:wolfenstein:Special:Wantedtemplates.
 * Transclusion rules: Transclude everything on the page.
 * Annoying  and   tags necessary to prevent the documentation page from being transcluded onto pages using the template.
 * Categories: Applied to both the Template: page and all pages into which it is transcluded
 * This is illogical: really, how many categories can logically apply to both content articles and to template pages?
 * Noincludes and includeonlys are necessary to use categories with templates in any logical fashion.

Now let's look at the system I propose - note that everything is tentative and up for discussion.

Template: namespace (modified)

 * Documentation: Stored instead in a neat, clean title: Template documentation: 
 * A small divider exists after the template content on the template page, explaining the documentation, followed by the documentation itself. This will be similar in format to the appearance of the existing Template:Documentation.
 * Access the documentation page from an item in the drop-down list by "Edit" or by a link in the divider.
 * Use of a new namespace allows for more functionality.
 * Transclusion rules: Transclude everything on the page, except the divider and documentation.
 * By excluding the documentation by default, it becomes very possible to have a useful template along with documentation, using zero noincludes and/or includeonlys.
 * Categories: Categories are only transcluded onto pages hosting the Template, and not applied to the Template page itself.
 * To apply categories to the Template page, add them to Template documentation: .
 * The Template Documentation: page itself does not have categories.

Other changes

 * There could be a few new Special pages.
 * Wanted template documentation (Templates without documentation)
 * Orphaned documentation (Documentation without templates)
 * As a new namespace, Special:Allpages would be filterable to only show "Template documentation:" pages.

What do you think?
Overall, I think that this would serve to make template-making a lot simpler, and probably inspire people to write more documentation in the first place!

I actually sent this in as a request to Mediawiki: link. I think it kinda slipped through the cracks and never received any attention, though. I really wish this could become a thing, whether it be as a Wikia-specific feature, a Mediawiki extension, or, Lord have mercy, if it would be added to core Mediawiki!

What do you think? Feel free to comment with any suggestions - everything I mention is subject to change with the community's thoughts.