Thread:User talk:Zakgreant/MediaWiki Technical Documentation Plan/Some History

It was I who created a lot of the current structure on MW.org. However, the sheer size of the task got the better of me, and so the structure was never completed to my full satisfaction. I am glad to see that someone else is stepping up to the plate, but it would be good if further development was a continuation of the good work done so far, rather than a complete starting-from-scratch.

To help with that, here are a couple of brief notes about the original intent - please contact me if you have any questions about this or anything else relating to the current site structure.

It appears that the current focus is on the developer documentation, but I think you really need to take a step back and look at the needs of the MW.org users as a whole before planning a restructure of the site for just one group of them.

In my structuring I identified three groups of users, as represented on the home page:
 * 1) Wiki Users - the end users whose only interaction with MediaWiki is through the interface of the software itself.
 * 2) System Administrators - the people who actually install the software, configure it, upgrade it, install extensions, etc.  Note that there is a distinction here between system administrators (responsible for installing and maintaining the software) and wiki administrators (those with sysop rights on the wiki).  When I use the term 'administrators' in the context of this discussion, I am referring to the former.
 * 3) Developers - People who work on producing the software, or other software designed to work with it.  That sounds like a pretty vague way of describing it, but I deliberately use that wording as it needs to include people who do not actually write code (translators/UI designers/project planners) and people who work on add-ons (extensions/bots/external tools/etc.) as well.  Note that it technically (historically) doesn't include technical stuff relating to WMF servers or deployment as this wiki was originally set up to make a distinction (and loosen the connection) between MW and WMF.  I personally feel that should still be the case, however the line here has blurred somewhat.

btw - ignore the fact that some people will fall into more than one of the above groups. When visitors come to the site looking for information othey will normally be coming in the context of one or other of these roles.

Obviously, there is some overlap of content. Some subjects apply to more than one of the above groups, however when that happens it is usually best to write separate content targetted at each group separately, and to locate it on separate pages. For example, there should be a page describing how to write extensions, targetted at developers, a page on installing extensions aimed at administrators, and pages about using common extensions aimed at wiki users.

Some situations are less clear-cut, however. A case in point being my friendly version of the download page, which was reverted by a developer to a more developer-focussed version. The current version will scare away any new or non-technical users. However my version was criticised for hiding away the information that more technical users might be looking for.

One of my big aims, which fell woefully short, was to set up a central hub for each of the above groups of users, with links to the most common help topics, separate FAQs targetted at each user group, 'how to get involved', etc. As it is, they are kind of dumping grounds for links, but I was hoping for something more like the portal pages on Wikipedia.

With the above in mind, thought may also need to be given on where content should be located. Currently, it is all grouped together in the Manual: namespace (aside from the Help: namespace, which I'll come onto). It is not completely clear what the main namespace is for, except "stuff that doesn't fit anywhere else". These are things that should be considered as part of this restructure. Some old discussion is at Project talk:Namespaces.

It is important to note that the Help: namespace is not the end-user documentation for MediaWiki. I should repeat that, because it is easy to pass it by without fully realising the implications: The Help: namespace is not the end-user documentation for MediaWiki.

The Help: namespace has a very specific aim, which is to provide a set of help pages that can be imported into a new MW install aimed at users of the wiki. It is therefore a cut-down and self-contained version of the end-user documentation, aimed at a vanilla MediaWiki install. These pages do not aim to be exhaustive. We should not be requiring end users to download hundreds of pages for their local help namespace. Therefore it may be desirable for some subjects to have just the overview and common uses covered by the Help: page and to omit certain advanced or infrequently used features altogether. This information will need to be covered somewhere on MediaWiki.org, but not in the Help: namespace.

Focussing back on the general documentation, one key point in the way these pages have been developed is that we aimed to cover all versions of MediaWiki with our documentation. This doesn't mean that we will go back and retro-actively create content for old versions - what it means is that we won't remove existing content just because it no longer applies to current versions of MW. I know from experience the frutstration that comes from documentation vanishing when software is upgraded.

This post has already got far too long, so I'm not going to go into some of the other areas I was going to write about (configuration settings/hooks/etc., extensions, the installation guide) but I would just say one final thing. There has been a lot of discussion, at various points, about various structural issues (e.g. use of sub-pages/namespaces/etc. and how things should be divided up) and I would be surprised if there is anything that you plan to do as part of this tidy-up that has not been discussed in some form before. Unfortunately, LiquidThreads seems to have made earlier history inaccessible so I can't find specific examples at the moment. The point is that some things that are inconsistent are deliberately inconsistent, because method A works better in one context and method B works better in another, some are inconsistent because a decision failed to be reached about the best method and some are inconsistent because a decision was reached but no one got round to doing it, or it only got partially done (e.g. moving content from meta). In anything other than the final case it is likely to be contentious to change things without developing a certain amount of concensus.

As I say, please contact me if you have any questions regarding any of this. I hope the project is successful and am happy to help out as much as my limited free time will allow.

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