Some History
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.
