Topic on User talk:Zakgreant/MediaWiki Technical Documentation Plan

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)

Aloha HappyDog,

Many thanks for taking the time to write!

As I write in the plan, my goal is "... to improve MediaWiki’s developer documentation by making small, incremental improvements to the existing documentation process and infrastructure." I don't want to reinvent the wheel. Of course, what I think is a small change may be seen as a large change by others. :)

I'd love to pick your brain about what you've done (or hoped to do) and why you did it. If you don't mind, perhaps the fastest way to do this is through a series of voice chats that I can transcribe – this should let me make the best use of your limited time.

As for the focus of the plan, it is very clearly on just the developer documentation – this is what the WikiMedia Foundation folks have asked me to focus on (along with the Mediawiki Technical Operations documentation). I do agree that we should consider all of MediaWiki.org. I think that I need to gain expertise (and community trust) in one area before really thinking about the larger issue of what should be done with MediaWiki.org. This is another topic that I'd like to discuss further.

I agree with your breakdown of users – and have the same breakdown in my plan (though I do explicitly call out and consider translators and extension writers as separate groups.) I also agree with your view on how people have different roles, depending on the task that they are trying to perform.

On the issue of pages where each audience has distinct needs, I rely on careful structuring – and, in some cases, separate pages – to serve the different needs. Take CSRF as an example – the first sentence in the overview is meant to be something that any of the audiences to MediaWiki.org can understand. The next sentence is meant to serve technical users, as is the example. After these bits of intro, the writing is focused on the main audience of developers. I plan to follow this kind of structure for everything that I do major edits on.

I'll take a look at Project talk:Namespaces - I've got thoughts here, but I can see comments about that in another message. :)

With the Help: namespace, I'd like for us to just be able to ship that with the MediaWiki tarballs. I am sure that there are solid reasons why we don't do this, but it still should be fixed.

In dealing with old versions and documentation, there must be a way to deal with this relatively cleanly. I've been thinking that even just doing an HTML dump of the relevant bits of MediaWiki.org would be better than nothing. I do wonder if we couldn't handle it like translations. eg. [[Manual:$wgDBadminpassword/1.12]] for the MediaWiki 1.12 $wgDBadminpassword docs.

Again, thanks for taking the time to engage!

Cheers!

I would prefer to keep discussion on-wiki, so that other people can see it and participate, if that's OK. I am aware of the very long thread recently in wikitch-l about too much face-to-face conversation, and not enough transparency and I don't want to exclude other contributors from the discussion. If there are specific things that would benefit from a Skype chat then I'm not totally against it, as long as it is transcribed, so if you feel a strong need then let me know. IRC is another alternative, of course, which would save having to do a transcription... ;-)

I understand your point that you are planning to start with small incremental changes. My worry would be that without a good overview of the project and what, in the long run, you intend to acheive for MW.org as a whole, it could end up being quite wasteful of effort. Make sure you aren't focussing on the climb before you've worked out whether you're on the right mountain!

The CSRF page is probably done 'right', and that highlights that there is probably no single generally-applicable solution. However if you look at it from the point of view of the three groups, the page is very definitely a developer focussed issue - i.e. "How, as a developer, should I code in order to mitigate the chances of CSRF?". It has a much smaller, secondary use for administrators - "What techniques does MW use to ensure my wiki is not vulnerable to CSRF attacks, and is there anything I, as an administrator, should be doing to further reduce this risk?". For the third group - wiki users - it has no relvance whatsoever.

Finally, in terms of the point you make about the help documentation, take a look at Project:PD help and Project:PD help/export. I envisage an MW plugin (or, ideally, core feature) where it can automatically download, install and keep up-to-date the Help: namespace of your local wiki, using whatever language(s) you choose.

I'm happy to keep things on-wiki or in other public text channels. Just let me know what works best for you. I suppose that my preference is a mix of LT discussions and IRC chats. LT lets us summarize and such, which IRC lets us short-circuit some kinds of potential misunderstandings.

I take your point about climbing the wrong mountain. At present, I'm focused on becoming a part of the community, improving the content of the docs, testing ideas from the draft plan and working with others to improve the draft. The metaphorical mountain-climbing will come later.

With the CSRF page, it is written for the primary audience - developers. It is relevant for wiki users only in that they may find their way to the page accidentally and should be able to figure out via the overview that it isn't a page for them. :)

Regarding the help docs, I can pros and cons to having a feature that pulls down the docs.

Pros:

• wiki is populated with most recent docs (compared with bundled docs, which would likely only be updated once per release.)

Cons:

• feature would disclose information by "w:Phoning home"

Issues:

• multiple runs of the feature would need to deal with the situation where the docs are newer than the version of MW pulling the docs
• multiple runs of the feature should not overwrite local edits

With regards to having the help docs in the default install, I think we can do both solutions! The new installer is going to (soon) have the ability to (optionally) phone home. The original idea behind this was being able to get statistics on installs and upgrades.

It would be (fairly) trivial to add a post-install step called "Setup help documentation." You could have the option of pulling the documents directly from MediaWiki.org (ensured to be up-to-date), or use the dump we packaged with the install (possibly slightly outdated, was dumped at package time).

At upgrade time, we could offer to pull the updated docs from MW.org, or use the (possibly updated) dump.

Do we have an existing plan for this?

Just some IRC chats over the summer (can try searching the logs if you'd really like). I wrote up a possible dial-home format, but it's more technical in nature.

As far as doing Help during post-install, there's a bit of info over at New-installer_issues#Features about some post-install processing we could do. But nothing's formal yet and that page is mostly a tracking page for outstanding issues.

At least there are some notes. Also, I didn't know about the log tool - handy.