Topic on Project talk:New contributors

Jump to navigation Jump to search

Improving programmer's documentation

4
Katkov Yury (talkcontribs)

I can say from project manager's point of view that it takes MORE time to prepare MediaWiki developer that Drupal/Joomla developer out of PHP/js programmer.

I've had employees and students, and many of them complains that there is no programming documentation in MediaWiki. This is not true, we have lots of docs for almost every hook, class and function. However I can admit that there is not much materials and article to glue together these specs.

In other words we have good reference manual but bad tutorial. The only thing that I can call 'a tutorial' is this one. It's a big mess now and it needs improvement:

  • first things first. i18n, aliases, $wgExtensionCredits and defining configuration variables are NOT the most important parts of the extension
  • Where are the BIG ideas? First big idea is that extensions use hooks mechanism. Second big idea is that extensions writes and reads directly from database, unlike plugins in other CMS. Third big idea is that there are two APIs - the PHP classes like Request, WikiPage etc and well-documented client API.
  • Documenting the PHP API: Hooks and PHP Classes. I really don't know how to better do that :(
Qgil-WMF (talkcontribs)

You are totally right. We have so many wiki pages combines with so much overlapping outdated pages, low quality ones...

You gave me an idea: let's mark the pages we MUST keep to high standards in order to attract and keep new contributors. I started using this category: Category:New contributors.

About tutorials for developers, what about

This post was posted by Qgil-WMF, but signed as Qgil.

Katkov Yury (talkcontribs)

There is something very nice in each of the tutorials

I can add also this page: MVL - such structure is very good idea and it can make a impression of well-documented software. Maybe such table of contents can be added to all developer documentation pages? See how it's done in Semantic MediaWiki user documentation.

Nemo bis (talkcontribs)

You're wrong on i18n, that's a requirement and making it sooner rather than later is better for everyone. ;-) You're right however on tutorials, and the main problem may be that we talk a lot about the API, meaning however only the WebAPI (probably for a bias, that people only want to interact with Wikipedia's data), and the PHP API doesn't even exist at all: I added a mention of the concept only few weeks ago on API.

Reply to "Improving programmer's documentation"