User:Zakgreant/pairdoc/2010-11-22
< User:Zakgreant | pairdoc
| [13:54] | <ialex> | hi |
| [13:54] | <zakg> | hey |
| [13:55] | <zakg> | so, i guess that you're pinging me about the offer to work on docs together. :) |
| [13:55] | <ialex> | yes |
| [13:55] | <zakg> | so - does the offer make sense and is it interesting to you? |
| [13:56] | <ialex> | yes |
| [13:56] | <zakg> | cool! so what things do you want to document and when? |
| [13:57] | <ialex> | I mostly maintain Manual:Configuration settings and Manual:Hooks |
| [13:57] | <ialex> | and some other misc stuff |
| [13:57] | <ialex> | e.g. Manual:Code |
| [13:57] | <zakg> | .. which are two large and hairy sections |
| [13:58] | <zakg> | ... both of which i've avoided taking a close look at |
| [13:58] | <zakg> | so, how can i help on them? |
| [13:58] | <zakg> | (or on other things?) |
| [13:59] | <ialex> | for the configuration settings and hooks, I don't see anything special to do |
| [13:59] | <zakg> | ok |
| [14:00] | <ialex> | it is just to keep them up to date |
| [14:00] | <zakg> | i'm happy to do sessions with you where we work on that together - as long as that is useful for you. |
| [14:00] | <ialex> | since other developers don't document new settings or hooks, or only in the software |
| [14:01] | <ialex> | Manual:Code might be more intresting |
| [14:02] | <zakg> | Ok. It seems that the challenge there is to avoid duplicating what's already covered in the doxygen docs |
| [14:02] | <ialex> | exactly |
| [14:02] | <ialex> | and also between Manual:$wg* and Manual:*.php |
| [14:03] | <ialex> | for global objects |
| [14:03] | <zakg> | Trevor and I have had some ideas on how to try and integrate the two - having an extension that displays the autogenerated docs with the docs in the wiki |
| [14:04] | <ialex> | that would be nice |
| [14:04] | <zakg> | I'm talking with Trevor on the 30th about the docs. I'm sure that you can join in or read the notes after, as you wish. |
| [14:05] | <zakg> | as for Manual:$wg* and friends, I can make sure that all of the right stubs exist and such. |
| [14:06] | <ialex> | normally I just copy the doc from DefaultSettings.php |
| [14:08] | <ialex> | but the problem is mainly http://www.mediawiki.org/wiki/Manual:Global_object_variables |
| [14:08] | <ialex> | (and the variables listed there) |
| [14:08] | <zakg> | ... just that not everything is documented? |
| [14:09] | <ialex> | actually this page is just a copy of http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/docs/globals.txt?view=markup |
| [14:09] | <zakg> | aha |
| [14:10] | <zakg> | so. we probably don't need two copies of the same info to maintain and the info is out of date... |
| [14:10] | <ialex> | I find the first section off topic |
| [14:12] | <zakg> | just looking at http://www.mediawiki.org/wiki/Special:WhatLinksHere/Manual:Global_object_variables to see what people think the page should be for |
| [14:14] | <zakg> | It looks the links fall into two categories - links that are supposed to go to documentation on a global variable (or all global variables) and links that are supposed to go to a page that helps devs understand that globals are evil |
| [14:14] | <zakg> | It seems like the current page should focus on documenting the globals and that the other pages that want to link to information on how evil globals are should be pointed at the style guide and security docs |
| [14:15] | <ialex> | yes |
| [14:16] | <zakg> | well then. why don't i take a shot at fixing that problem and then perhaps we could work on improving Manual:Global_object_variables together? |
| [14:17] | <ialex> | why not? :) |
| [14:17] | <zakg> | heh |
| [14:18] | <zakg> | ok. i'll go do that and then see if we can find a time to work together on Manual:Global_object_variables |
| [14:18] | <ialex> | just one question, your job is only for mediawiki.org or also for the software doc? |
| [14:18] | <ialex> | (I'm speaking http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/docs/ ) |
| [14:19] | <zakg> | i've been working only on MediaWiki.org but i'm starting to work through the source docs as well |
| [14:21] | <zakg> | i'm happy to set up sessions to walk through a particular source code file and document as we review. i've started this on OutputPage.php with hashar |
| [14:22] | <zakg> | i need to clean up our work and submit the patch in the next day or two |
| [14:45] | <ialex> | also something that is a mess: http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/docs/title.txt?view=markup |
| [14:46] | <zakg> | Yep. kaldari and roan have flagged this for me as well |