User talk:Zakgreant/MediaWiki Technical Documentation Plan

Previous page history was archived for backup purposes at User talk:Zakgreant/MediaWiki Technical Documentation Plan/LQT Archive 1 on 2015-07-10.

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.

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.

A few things came to mind just now, and I thought I'd see what your thoughts were. Currently, Mediawiki.org is trying to produce public domain Help pages. Unlike the manual, which is geared towards wiki and server administrators, the help namespace is designed to be for the end-users and contain information on how to edit/search/use the wiki. The pipe dream would be to one day package these into MediaWiki itself in an initial installation. What are your thoughts on this? Also, as a source of content for our (rather sparse) Help namespace...could we turn to the English Wikipedia for some guidance? It certainly has a more comprehensive help section (much would be out of scope for most wikis, however).

User docs/help should be distributed with MediaWiki – there's little point in making every installer jump do this same small task. For now, I'm focused on the developer docs, but I suspect that I'll be tasked with working on the user docs in the future.

I noticed you had the following tidbit:

Additionally, there is some developer documentation that has not yet been migrated from meta.wikimedia.org (see Meta:MetaProject to transfer content to MediaWiki.org).

I just wanted to point out that the information on Meta is very outdated. Most of what's left isn't even really useful.

Thanks for the note!

I think that most of the work in migrating/handling the developer-related content on meta is going to be redirecting folks to the right pages on mw.o. We need to do this, as there are still links out there to content on meta.

• §3.1 : Various tools and resources also rely on the current structure, making structural changes a complicated and detail-oriented task.

  What "tools and resources" are you talking about? An example or two would be helpful.

• §3.9 : The overall process should help advance Wikimedia communities. [...] The Wikimedia community should be interested in and willing to work on the documentation.

  Do you really mean "Wikimedia" here? Or MediaWiki? I'd say MediaWiki, but the context doesn't really help disambiguate.

Overall I think it's a very good document detailing the current and the ideal status. The guidelines are sensible and useful. What seems to be missing is how we can actually get there. Perhaps it wasn't part of the deliverables, but without a clear action plan it's difficult to really know where to start.

Thanks for all the feedback and edits, guillom!

• Re: What "tools and resources" are you talking about? An example or two would be helpful. – I've added a few examples (mw-bot and the mailing lists.) In the case of mw-bot, it's factoid db can be updated. In the case of the list archives, these can't be altered - the links listed in the various messages need to be preserved.

• Re: Do you really mean "Wikimedia" here? Or MediaWiki? I'd say MediaWiki, but the context doesn't really help disambiguate. - When I started writing this plan, it had a larger scope and an underlying intent to be applicable to many Wikimedia projects. Now that I've trimmed the scope back, I should change this. Thanks! The name soup that we swim in sometimes baffles me. :)

• Re: What seems to be missing is how we can actually get there. Perhaps it wasn't part of the deliverables, but without a clear action plan it's difficult to really know where to start. – I've left that bit out. It was part of the deliverables and an earlier draft of the plan, but I had a change of heart on how to get there. I'll add details on my current thinking shortly.