Topic on User talk:Zakgreant/MediaWiki Technical Documentation Plan

we should adopt Wikipedia's approach of using simple titles for pages and then disambiguating as needed. This allows users to browse the documentation in a very natural fashion and quickly move between related concepts with similar names. This has already been done, but not nearly as consistently as is needed.

Not sure I agree with that. The reasons why Wikipedia moved to a flat namespace do not apply here. Theirs was a problem of categorisation: Should the article about the history of Algeria be in 'History/Algeria' or 'Algeria/History'? We don't have that problem - we have some items that make a lot of sense to have in sub-pages: Hooks, Config variables, Class structure (already a heirarchy in itself). The big advantage of sub-pages is the instant navigation that it gives back to the parent.

There are also things such as minutes of meetings, or the markup spec, which suit a heirarchical arrangement. The thing to remember here is that there are a multitude of uses on this wiki, as opposed to the single use that most other WMF wikis have (encyclopedia/dictionary/etc.). Related information needs to be grouped to a certain extent in order to stop us all going mad, and the two mechanisms we have are sub-pages and namespaces (and I don't think we need more namespaces...).

The alternative to sub-pages is to manually create the necessary back-links on each page that is part of a logical group, but this makes for a lot of extra work, given that the software can do this for us, and it invariably ends up looking ugly.

--HappyDog 03:55, 5 October 2010 (UTC)

I would have to agree with HappyDog here, Comparing the data on MW.wiki compared to EN.wikip is like comparing apples and oranges, We serve a different type of data which is more suited to being in subpages compared to a flat system, for example, as HD mentioned the Meeting pages where the subpages are directed related and would make less sense to not have them in a subpage system. Although it should be noted that most of our content doesn't actually use pages apart from language translations (Exmaple: Sites using MediaWiki and Sites using MediaWiki/ru), Those would also make no sense in moving from a subpage system.

I can see now that I wasn't using the right language to describe what I mean. Let me go fix that. ... Ok, I've stripped out the "Flat Namespaces" bit.

Now, on the actual issue as I understand it (and I'm happy to learn more and change my understanding. :)

The current situation is that one topic may be covered in different ways for different audiences. Take Parser functions as an example:

• A user may simply want to know how to use conditionals in a template (and good luck to the poor devil – figuring out that conditionals live in an extension called ParserFunctions isn't exactly intuitive.) They need Help:Extension:ParserFunctions
• An administrator will want to read Extension:ParserFunctions, so that they can understand how to install the extension.
• A developer who wants to write their own parser functions will want Manual:Parser_functions

It's clear that each of these namespaces is needed. It's also clear that Parser functions in the main namespace is pretty essential to help folks find what they need.

As a side note, there should also be pages like: Conditionals, If and Switch. As Rasmus from PHP says, "Information should be where people look for it." No user is going to go looking in Parser functions.

I think that someone should be able to visit http://mediawiki.org/wiki/'''topic''' (where topic is some reasonable thing like If or Bold) and get a reasonable response. (Also, it'd be even nicer if http://mediawiki.org/'''topic''' worked.

We need to be more consistent as well – users are likely to be a bit confused at how ParserFunctions takes them to Extension:ParserFunctions, while Parser functions takes them to a disambiguation page.

The reason those redirects exist (EG: ParserFunctions → Extenstion:ParserFunctions) is because when you search by name, it won't automatically redirect when they are in a namespace other than the Main, although I have submitted a bug for that to be looked at (bugzilla:25432). Whilst I/we do try to get rid of some of the cross namespace redirects when they get created, we can't exactly purge them all since we can't tell what outside sources point to them that easily and risk breaking links.

Redirects like this are still pretty confusing for people. One wouldn't expect Parser functions to point to a different place than ParserFunctions.

As a side note, there should also be pages like: Conditionals, If and Switch. As Rasmus from PHP says, "Information should be where people look for it." No user is going to go looking in Parser functions.

I think if pages like that are going to exist, they should redirect to the appropriate section. There's a benefit to keeping the stuff in one article (easy to reference different sections while reading, for example). Redirects can point to sections, so it something like Conditionals -> Parser functions#Conditionals would both ease searching and keep the documents grouped logically.

I agree. This also makes it easy for us to handle changes in a sane way. Using parser functions as an example, if/when the functionality gets rolled into core, we can easily point Conditionals to a new page.