Project talk:Manual

Category:Manual

I propose we use Category:Manual instead of Category:MediaWiki Manual. Nothing on the site is about anything except MediaWiki. So putting MediaWiki into the category name complicates things unnecessarily. Keeping it just Category:Manual makes it easier for people to type it the same ever time. If no one objects, I will make this change next week. --Rogerhc 05:33, 14 August 2006 (UTC)

Yes I'd agree with that. -- Harry Wood 18:42, 27 June 2007 (UTC)

Manual: namespace

There's a question posed on this project page:

• What content should be in the Manual: namespace?
• What should not be in the Manual: namespace?

Do we answer this question anywhere? If not ...well what is the answer?

-- Harry Wood 18:42, 27 June 2007 (UTC) (...ok 2 questions)

The answer is that there is no official position, and that it has not really been discussed properly yet (which is why the questions are still there). As far as I am concerned the manual: namespace should contain all instructional information about the software (not extensions, etc.) except for the information held in the Help: namespace. The main namespace would then be used for development discussion, test-cases and notes. However that is only my opinion. If you are referring to the Installation/Manual:Installation issue specifically, then in my opinion they should be kept separate. The former is part of our quick introduction, and doesn't deal with anything too technical. The latter is a much more detailed installation guide. However I can see an argument for moving them to Manual:Installation and Manual:Detailed installation notes, respectively (but not merged - that would be too daunting). --HappyDog 18:34, 14 July 2007 (UTC)

I was chatting to Tim and Angela about mediawiki.org (at a London Wiki Wednesday meet-up). They immediately mentioned this namespace as a confusing factor. There are disadvantages to using namespaces. They're harder to search, harder to link to, and generally less newbie friendly, but I suppose it's too late for me to suggest moving everything out of the Manual namespace!

Anyway there are advantages too of course. So maybe we view it as a more 'polished' set of pages under the 'Manual' namespace, and then we keep the more chaotic wiki expansion within the main namespace. Main could also be viewed as an incubator for information which could be written properly and moved into the manual, and conversely area for demoting information out of the manual which is not well polished (development discussion and notes as you say)

The trouble is, if you create a page on a topic relating directly to mediawiki, then it's likely that that topic ultimately belongs in the manual. The distinction is not really a clear one. Maybe it doesn't matter, because things can be moved later, but people like to add stuff and link it in the right place.

-- Harry Wood 08:59, 24 July 2007 (UTC)

The manual namespace is searched by default, unless you registered here before that option was turned on (Hmm... I wonder if we could run a bot to update all old users to include it?) so searching shouldn't cause any problems. I also don't think that it's particularly harder to link to. I concede that if you aren't sure where the content is then it is hard to link for, but in practice this applies to the page name too (is it Manual:Upgrading or Manual:Upgrades or Manual:Upgrading MediaWiki? You still have to find the page to make sure... and in this case, it's none of them, but two of them are redirects, and that is a problem that has nothing to do with the namespace). I would like to hear your reasons as to why it is less newbie friendly though, as I've not considered that before.

Personally, I think the idea of staging in the main namespace and deploying in the Manual: namespace would be a lot more confusing than the current situation. In particular, there are lots of pages that should definitely not be moved in this way, for example the Configuration settings - it would be mayhem if the 'good' ones were in the Manual: namespace and the 'ones that need work' were in the main namespace.

My general feeling is that if we clearly define what should be in each namespace (which we are not doing at the moment, or at least not explicitly) then a lot of the confusion would go away. --HappyDog 16:31, 24 July 2007 (UTC)

We now have a Project:Namespaces page which attempts to explicitly define the intended contents of each namespace. I'll take any further discussion to that page. -- Harry Wood 17:12, 12 February 2008 (UTC)

Manual: Proposed Clearer Navigation/Layout (Page moves and template changes required)

1. I propose that we add a contents link to Template:Hubs so that it is made more clear that the developer, sys admin, and user hubs are in fact sections of the Manual as this is not at all clear at the current time and in fact extremely confusing (i am constantly going to all sorts of pages to search for extension writing info).
2. Proposal 2 is this: move stuff away from the Manual:contents page and onto whichever hub page it belongs to. Having half the developer links (Manual:Code,Manual:MediaWiki_hooks,Manual:Parameters to index, API) on the Manual:Contents page mixed in with mediawiki installation stuff, faq and other crud is just plain awful. Not to mention that the other half is located on the developers hub (and in fact some of the more important extension writing info wasn't even directly linked to from there till I added it). I realize this will be controversial as I have read that some people belive that the manual should be exclusive to well developed pages, but then if its not linked to from the manual, where the heck are people going to find the info they need to make mediawiki better? I mean I had to search to find some of the pages I most frequently use and personally i am not a fan of having to rely on MW search. ever.

Please comment on this, I hope it doesn't come across to rant like, I'll be back in 2 weeks to see what people are saying, if alls good I'll go ahead with these changes.

PS. Check out my extension User:Diploid/ATS (Article Tagging System) :)
--Diploid 07:43, 17 August 2007 (UTC)

Update: As per Cneubauer's comment below I will be going ahead with these changes early next week if no one has anything else to add to the discussion. --Diploid 23:09, 22 August 2007 (UTC)

See below. --HappyDog 16:16, 27 August 2007 (UTC)

Yes, but seeing as none of those long term mw users appear to be around to comment on my proposal I'm going to go ahead with part 1 which is very easily reversible if people don't like it. Also if you've got any comments on my ideas HappyDog, any help is greatly appreciated. --Diploid 14:03, 29 August 2007 (UTC)

As stated, the hubs are not part of the manual. It would make more sense to have a link back to the main page than to the manual contents, but as that is already present on every page anyway, it would be a little redundant, I think. I have reverted your change. The point of the user hubs is to give a user-centric site navigation. To include a link to a general contents negates that, in my opinion, particularly as there is a 'manual' link in the sidebar. --HappyDog 17:13, 29 August 2007 (UTC)

I see your point, but the manual link was one of the major reasons for my initial confusion when modding mw software. I'm just coming at this from the point of view of someone who wants to write an extension or (god forbid) work on the core mediawiki software. And from that perspective I want to be able to find everything I need from one spot on mw.org, be it in the manual or elsewhere. But the last thing I need is to have to go back and forth between a bunch of seemingly loosely related pages with no discernible hierarchy. The Manual needs hierarchy just like the help pages have now and without that it will never be of much use to anyone. --Diploid 20:04, 29 August 2007 (UTC)

True, and that is something we are working towards. In your case, you should be able to access everything from the developer hub, as that is the whole point of it! If that is not currently the case then it needs addressing. --HappyDog 21:11, 29 August 2007 (UTC)

I still think the template is more useful with the contents link for now. Manual:Contents is currently the one and only jumping off point for the hubs. The hubs provide the only structure the developer pages have. Until they are complete and have their own navigation templates and users can find them just fine without Manual:Contents, I would recommend putting the link back in. --Cneubauer 11:51, 30 August 2007 (UTC)

Restructuring the Manual

The developers section of the manual is needlessly complex. Its very difficult to find information on how to write an extension since its spread between Category:Extensions, Manual:MediaWiki hooks, Extending wiki markup, Writing a new special page, Extensions FAQ, Manual:MediaWiki hooks, and Manual:$wgExtensionFunctions. Extending wiki markup and Writing a new special page are good but should be renamed. I propose we have a page for each method of extending MediaWiki: Hooks, Tag Extensions, Parser Extensions, Special Pages, and Skins. Each page would describe how to write that type of extension, best practices, common mistakes, and would provide a general FAQ for that type of extension. If any of the documentation is specific to the latest version of MediaWiki, links to documentation for older versions should be provided in an infobox at the top of the page too. This would prevent the clutter of each section of a page having a multiple subsections for older versions. --Cneubauer 15:28, 21 August 2007 (UTC)

Support I like this idea, finding extension information is currently far to difficult and compatibility issues of new extensions can only really be figured out by trial and error. If my proposal (see above) is accepted I would think a combination of these two ideas would help new extension writers greatly by making vital extension developer information easy to access. --Diploid 01:32, 22 August 2007 (UTC)

I doubt we are going to get much feedback on this page so if I don't hear anything by this weekend, I'm just going to do it. I would say go ahead with your ideas too. They seem logical to me. --Cneubauer 15:29, 22 August 2007 (UTC)

Agreed, I've updated my thread to reflect this. If your interested in collaborating on other changes to the manual (of which it could certainly use quiet a few) please don't hesitate to contact me. --Diploid 23:13, 22 August 2007 (UTC)

Please do not make such radical changes without proper discussion with people (not necessarily admins) who have been here for a long time. We quite often get people who want to re-organise the wiki, and they usually end up making a mess of it because they have not discussed it with people who understand the reasons behind the current organisation first. I agree that there are problems that need fixing, but before going any further, please give more specific details about what you plan to do and why. This goes for the previous thread by Diploid as well. Sorry for the delayed response - I would have replied sooner, but I've been away. --HappyDog 16:15, 27 August 2007 (UTC)

Information for developers has been a terrible mess since MediaWiki wore shortpants. Extension writing pages specifically have always been all over the place. There are six pages on writing extensions, two on skinning, and at least two on coding conventions and people still complain that the documentation is bad. So I decided to be bold. Anyway, I already made all my changes but one. Here's a list:

• Added a new template, Template:ExtensionTypes which links to pages relevent to developers.
• Moved three pages to the manual namespace and made simple clear names for them: Manual:MediaWiki hooks --> Manual:Hooks, Extending wiki markup --> Manual:Tag Extensions, Writing a new special page --> Manual:Special Pages.
• Broke parser function information out of Extending wiki markup to Manual:Parser Functions.
• Added some content and better links to all these pages.
• I still haven't cleaned up the skinning information. All the good skinning info for devs is on Manual:Skinning. Manual:Skins is kind of worthless. I will probably change the template to point to skinning instead of skins.

--Cneubauer 16:38, 27 August 2007 (UTC)

All the sub-pages of Manual:MediaWiki hooks need to be moved as well, and the links in the main page should be restored to their 'relative link' form. Note that page names should be in sentence case, so Manual:Tag extensions instead of Manual:Tag Extensions. You also need to update incoming links to avoid redirects. Otherwise good work. --HappyDog 17:22, 27 August 2007 (UTC)

Thanks. Yeah I commented on the need to move hooks when I moved that page. I will do that tonight. I think we can also get rid of the two versions of the table, one alphabetical and one by version since the table can be made sortable. --Cneubauer 17:41, 27 August 2007 (UTC)

Maybe - how does the sorting code handle numbers? E.g. will it sort 1.1.0, 1.2.0, ... , 1.10.0 or 1.1.0, 1.10.0, 1.2.0? --HappyDog 18:10, 27 August 2007 (UTC)

<----

It sorts the wrong way but according to this page: m:Help:Sorting#Sorting_with_hidden_sortkey you can add a hidden sort key to fix it. I tried it out and it works fine now. Is that "sentence case" rule a must? I think the page looks better with both words capitalized. They are after all titles. You wouldn't write a paper or a magazine article and call it "Tag extensions". I know alot of wikis have had these discussions in the past and worked out a way of doing things so if you have here as well that's fine with me. --Cneubauer 20:56, 27 August 2007 (UTC)

The convention on this wiki is to use sentence case, though that hasn't been formally written down anywhere, and there are no doubt exceptions that haven't been fixed. In short - yes, that's how it's done here :-) --HappyDog 22:59, 27 August 2007 (UTC)

Structuring Manual/Help Information

I've been gathering links for a while and posting them at Developer hub. I would like some feedback on structuring all of these pages into a useful body of work. According to Project:Namespaces, information is broken down into Help pages for general user help and Manual pages for admins/developers. Template:Hubs however breaks things down further into three separate sections for users, developers, and admins. We don't really handle this in a structured way though. As I see it, each topic needs an overview page and 2-3 user role specific pages. An overview page, Manual:Skins for example, might have links to Help:Skins for users, Manual:Skinning for devs, and Manual:Skin configuration for Admins. Here is a breakdown for some topics:

	Code	Database	Extensions (Manual:Extensions)	Skins (Manual:Skins)	Special Pages	Namespaces
Users	None	None	Help:Extensions	Help:Skins	Help:Special pages	Help:Namespaces
Devs	Manual:Coding conventions	Manual:Database	Manual:Writing extensions	Manual:Skinning	Manual:Special pages	None
Admins	Manual:Code	Manual:Installing_MediaWiki#Create_a_database?	Extension Matrix	Manual:Skin configuration	None	Manual:Namespaces

These pages would also need to be merge in or linked to from one of the above:

• Extensions:
  • Manual:Hooks
  • Manual:Tag extensions
  • Manual:Parser functions
  • Manual:Special pages
  • Manual:Skinning
  • Manual:Magic words
  • Extensions FAQ
  • Extensions
  • Category:Extensions
  • Manual:$wgExtensionFunctions
• Database:
  • Manual:Database layout
  • Manual:Database access

This overview pages would let users browse all the pages related to code for example. There would also be templates that let users browse by mission (Template:InstallationNav, Template:ExtensionTypes). Comments? --Cneubauer 14:58, 30 August 2007 (UTC)

The division of the namespaces is not quite as you've described, and indeed there is still a bit of debate about what goes in the Manual: namespace. Here are the differences.

• Help: - This is a set of public domain help pages designed to be imported into a new wiki to give a basic set of user help. This will not contain any developer or system admin information (though it will contain info relevant to wiki admins - the distinction is 'system administrators' are people who manage the wiki at a server/software/hardware/db level, whilst 'wiki administrators' are people who have special administrative powers on the wiki itself, e.g. blocking, deletion, etc.). In practice, there may be topics that are useful to end users, but are not appropriate in a generic set of help pages for whatever reason, and if so, these will go in the Manual namespace.
• Manual: - The debate about this namespace is whether we should include all reference material, or only fully developed and structured articles (using the main namespace as a staging area for articles in development). Personally I am against this as it causes more problems than it solves, so in my view the Manual: namespace is for all articles about the software. There may be duplication within the namespace or between manual/help if that is thought useful. For example, Help:Skins might give basic generic info for users telling them how to pick a skin and what the default skins are, whereas Manual:Skins might give more detailed information about the same topic. You can already see this in action at the installation pages, where different systems have their installation instructions, which are largely similar except for system-specific issues.

So for the moment at least, it is not a correct assumption that all information for users will be in the Help: namespace, and also the distinction between admin/dev/user help is not always completely clear-cut. For example, editing system messages is something that is relevant to both sysadmins and to users.

Anyway, I've run out of time now, so I'll come back and comment on the other stuff soon.

--HappyDog 15:26, 30 August 2007 (UTC)

A missing group in the users/admins/developers breakdown

I'd like to propose a fourth category to the user/admin/dev breakdown -- I'm not sure of a good catchy name for it, but it is something along the lines of requirements analyst or business analyst. Whilst the manual has lots of information that would be helpful to this group, it isn't organized from their point of view.

This group has questions all its own. Admin material is too technical - an analyst really doesn't care about installation details or platforms - just that everything works once it is installed. Developer information is way too technical - analysts mostly care about "Why would I want to do this?", not "How do I do this?". End user material spends more time on the whys, but it does so from the point of view that the MediaWiki installation is a given. An analyst is trying to evaluate what customizations, if any, should be made and why.

Some questions typical of the analyst community:

• what are the organizational needs that could/should affect customization?
• are there patterns of organizational use that we can learn from?
• what are our options for increasing ease of use?
• what are our options for protecting the quality of the information in our wiki?
• what time,cost, and support issues are involved in customizing our installation?
• if there is more than one way to customize, which will give the best results? which will be easiest/cheapest/least timely to maintain? are they the same?

Any thoughts? Egfrank 09:08, 5 September 2007 (UTC)

Templates

I see that there is currently a rather thin page at Help:Templates, but nothing at Manual:Templates. There is a lot of material at meta:Help:Template, meta:Help:Advanced templates and (the reason I'm here) meta:User:Happy-melon/Templates, that should be moved over here. The question is, is it acceptable to split up the content and move things like $wgNonIncludableNamespaces to the Manual: page, leaving pure editing guidelines at the Help: page? If not, what should we be doing? Happy-melon 20:57, 30 June 2008 (UTC)

Rewritten Windows 7 Install Guide

After asking a random question in freenode IRC #mediawiki, someone asked me if I would write a HowTo. Well, I did, it's on my User Talk page: http://www.mediawiki.org/wiki/User_talk:Dbeiler

I wash my hands of it for now, and leave its contents, in all good faith, to the more learned documentarians who inhabit this wiki. You can email me too, though, should the need arise.