IRC office hours/Office hours 2010-09-29

<zakg> aloha
<zakg> who is here for the office hours session in a few minutes?
<werdna> me, assuming I can keep my eyes open :)
<Nikerabbit> me, before I leave for sauna
<werdna> sauna?
<werdna> crazy finns :)
<zakg> ok then. well, it's a small, intimate gathering. :)
-*- zakg smacks forehead for forgetting to promote this session
<str4nd> werdna, you don't know what's crazy if you don't try ice swimming
<MaxSem> everyone who's not hanging around on IRC is not developer enough, so it's ok
-*- RoanKattouw is sort of idling here
<zakg> MaxSem: That may not be so off the mark.
<zakg> Ok then. Let's get started.
<zakg> I'm Zak Greant – I'm a tech writer and open source generalist who has been contracted by the WikiMedia Foundation to work on the MediaWiki developer documentation.
<zakg> For much of the summer, I worked half-time. Most of this time was spent on reviewing the existing docs, talking with developers and working up plans to make the documentation process go smoother.
-*- guillom waves
<zakg> One of the key results of this work was a draft plan for improving the developer docs development process (http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan)
<Nikerabbit> the review probably was fast... or did you find any existing documentation :)
<zakg> Nikerabbit: as far as open source projects go, it wasn't too bad.
<Nikerabbit> that's surprising
<MaxSem> Nikerabbit, we are large enough. smaller projects are usually much worse
<zakg> There is information, it's just scattered and has inconsistencies (see http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan#State_of_MediaWiki.E2.80.99s_Developer_Documentation)
<Nikerabbit> maybe it's the scattered nature that gives so bad impression about it to me
<zakg> It is rough for new developers.
--> tomaszf (~tomaszf@216.38.130.163) has joined #wikimedia-office
<zakg> I spend time at WikiMania talking with non-core developers about how they learned how to work on MediaWiki. It was really clear that most of them had no idea where to find all of the bits of info that are out there.
<zakg> Right now, I think that one of our key challenges is to make is so that people can find the info that we already have.
<zakg> However, what I think can likely wait. :)
<Nikerabbit> most of the extensions (especially outside the svn repo) look like they never heard anything about mediawiki api and coding practices
<zakg> the few extension developers who I talked to said that they worked from existing extensions.
<werdna> that's how I started
<werdna> my first extension was almost a verbatim copy of another extension, with a few lines' modification
<MaxSem> Nikerabbit, they are not obliged to. even my proposal to delete extensions with known vulnerabilities if they're not fixed has met a serious opposition
<zakg> What I'd like to hear from people is why they are participating in this session, along with what they'd like to see done with the docs.
<werdna> Even up to just before I started at the Foundation, my way of figuring out how to do something was to find an extension that did something similar and read the code
<werdna> zakg: I guess a lot of us, including myself, are here because we're MediaWiki developers, we care about MediaWiki, and we feel like we have a stake in something like this
<Nikerabbit> zakg: I've paid a lot of attention to the documentation of my extension lately: ( http://translatewiki.net/wiki/Translating:Documentation http://translatewiki.net/wiki/Roadmap/Documentation ). Besides that I'm interested in having user documentation in a shape that could be translated
<zakg> werdna: I tend to do the same. I've not thought to check if we have a good sample extension that follows best practices and that includes verbose comments.
<MaxSem> zakg, there's Awesomeness for that, but it's too simple
<zakg> werdna: ok. no surprises there. :)
<zakg> Nikerabbit: thanks. i've got an interest in making the docs easier to translate as well.
<Nikerabbit> zakg: and obviously I would want them translated with the great tool I'm making :)
<zakg> MaxSem: Pearhaps we could polish some of the popular extensions that people are likely to use as starting points?
<zakg> Nikerabbit: Neat. Perhaps you and I could chat in the near future about translation and localization?
<Nikerabbit> zakg: yes!
<Nikerabbit> in a broader scope we should get our extensions in better control, mark the ones that are of good quality and ship the best and most used extensions with mediawiki itself perhaps
<werdna> though that's not really documentation-specific
<zakg> Nikerabbit: As we say in documentation circles, that topic is beyond the scope of this documentation. ;)
<MaxSem> zakg, some of extensions used by WMF are in pretty good shape
<werdna> zakg: I would favour using examples from other extensions liberally
<werdna> in our documentation
<zakg> MaxSem, werdna: We can likely do both.
--> siebrand (~beis@sm.xs4all.nl) has joined #wikimedia-office
<zakg> Ok. If there's nothing else that people want to share about why they are here, then I'd like to get feedback about what I'm currently doing.
-*- zakg waits a moment
<zakg> Ok.
-*- werdna is still getting through the page
-*- guillom has provided feedback on the talk page already
--> ^demon (~chad@mediawiki/demon) has joined #wikimedia-office
<siebrand> can someone repeat the link pleas? I just dropped in. A link to the log would also do...
--> Ryan_Lane (~Ryan_Lane@216.38.130.166) has joined #wikimedia-office
<werdna> http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
<siebrand> tnx
<werdna> It's very thorough, and a very good introduction to where we want to go with documentation.
<werdna> I suppose the next step would be to figure out how to action it :D
<guillom> that's basically what I said :)
--> Tiptoety (~Tiptoety@wikipedia/Tiptoety) has joined #wikimedia-office
<zakg> werdna: indeed. that's what guillom said
<werdna> I'd like to see some discussion of integrating the workflow.
<zakg> let's chat about that a bit - it fits in well with where i was going
<zakg> As we all know, there has been concern around how the WikiMedia Foundation contractors and community communicate and work together. These issues became prominent around the time that I was getting close to finishing my first plan for the docs.
<werdna> For example, we have documentation comments for some (not as many as we should) functions, classes etc, and all configuration variables.
<MaxSem> zakg, what I don't like about our current docs are their entry points, http://www.mediawiki.org/wiki/Manual:Contents and http://www.mediawiki.org/wiki/Help:Contents
<werdna> It would be cool if we could somehow extract those and seed our documentation with it.
<zakg> The first plan focused on a complete and structured overhaul of the documentation. I felt that it would be best to address the various issues by starting with a blank slate and doing it right.
<werdna> (and, far-future, it would be cool if we could have search results within the code of usages of a function / variable). Of course I'm talking about code-level documentation.
<zakg> This would let us fix the structure of the docs so that there could be things like clean entry points, plans for coverage, etc.
<zakg> The challenge in doing this is that it would basically be a WMF contractor trying to force process down the community's throat.
<zakg> So, I scrapped the plan and worked up the draft that you've been looking at.
<zakg> It
--> GerardM- (~chatzilla@ppp-115-87-86-49.revip4.asianet.co.th) has joined #wikimedia-office
<zakg> is very focused on the issues and the end goals, but steers away from issues of big process.
<Nikerabbit> werdna: doxygen can do that to some extend: http://translatewiki.net/docs/Translate/html/interfaceMessageGroup.html#5c6939037c842edb68127541bde645ec
<zakg> I'd like to work on developing the process with the community and after I've had a chance to test the key ideas in the plan.
<werdna> I like your focus on pragmatism in the plan, it's very refreshing over what you usually hear, which is cries of "Everybody must be FORCED to document", and so on
<zakg> I also want to do these things *after* people have gotten to know me a bit.
<zakg> werdna: I've found that if you force people to document, at best, you get low-quality documentation.
<zakg> So, what I'm doing for the next few weeks is roughly this:
<zakg> * answering questions on the various mailing lists, so that I can learn and so that the devs can see me doing (or, in some cases, trying to do) useful work following the community norms.
<zakg> * Getting into the habit of making my activities usefully transparent. I've set http://www.mediawiki.org/wiki/User:Zakgreant up as a dashboard for my activities. I'm publicly posting my weekly reports and keeping daily public logs of what I'm working on. I'm still figuring some things out, but I'm happy with the early results.
<zakg> Expanding my knowledge of MediaWiki by browsing the source, reading the docs, editing docs pages, writing bits of code (like http://userscripts.org/scripts/show/79234), etc.
--> Lcawte (lcawte@wikia/wikimedia.Lcawte) has joined #wikimedia-office
<^demon> zakg: You've got commit access, right?
<zakg> * I'm also starting to do things like review pending changes for mediawiki.org, so that I can help people who are already doing things keep doing them.
<zakg> ^demon: I haven't asked for it yet. I know that I should.
<^demon> Gotcha.
-*- zakg adds it to his todo list
<GerardM-> are MediaWiki developers working outside the WMF and Wikipedia also your audience ?
<siebrand> Too bad ialex isn't here. He's doing a lot of source code docu updates. Have you already spoken to him, zakg?
<RoanKattouw> ^demon: Do you have the power to give access too, now?
<zakg> GerardM-: I'm focused on serving all MediaWiki devs. I've got more notes on this at http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan#Audience_for_the_Plan
<^demon> RoanKattouw: I just have access to the queue and the repo, I'm not a sudoer so I can't add users.
<RoanKattouw> Right
<^demon> (Might be worth asking the Powers that Be, so Tim's not the only one)
<RoanKattouw> Figured we might wanna have someone around when Tim is on baby leave
<zakg> siebrand: Thanks for the tip. I'll catch up with him (and see if he can come to my second office hours session in 12 hours.)
<siebrand> zakg: will let him know if he pops in.
<RoanKattouw> I think ialex is French, so probably not
<guillom> he is
<guillom> or Swiss
<werdna> he's Swiss, from a place that I'm blanking out on
<werdna> begins with L
<zakg> siebrand: thanks
<werdna> Lausanne
<zakg> lausanne? (sp?)
<zakg> So, does how I'm handling things make sense to you all?
<guillom> Lausanne, yes
<werdna> more or less. Have you thought about how we might implement such a system?
<zakg> Yes. I think that the process will have a few major moving parts.
<zakg> I think that the parts are roughly: planned improvements, reactive improvements and automated processes.
<zakg> Planned improvements would be an ongoing cycle of reviewing the docs, choosing areas to enhance and then working on them. For example, one week, we might focus on making all of the docs on variables more consistent.
<zakg> Reactive improvements would be what I'm doing now on the lists - as people provide information that isn't in the docs, we work to integrate it. We can't really plan this work - we just need to be ready to spend some time each day doing it.
<GerardM-> I have the impression that WMF is moving towards a more agile approach. Documentation is part of the deliverables of a sprint. Are your cycles sprints ?
<zakg> The last chunk is having automated tools to help us know when we need to add, remove or otherwise change the docs. This includes things like mapping documentation pages to code so that we can flag pages when the relevant code changes.
--> dgultekin (~dgultekin@216.38.130.166) has joined #wikimedia-office
<zakg> GerardM-: I'm going to try to follow what the community as a whole does. Right now, there isn't a consistent approach. If the community adopts something consistently, I think that the docs team should try to match it.
<GerardM-> :) thanks
<zakg> At a meta level, I plan on doing part of all of these things to help them become something that others in the community can adopt.
<zakg> Right now, I'm starting with the easy stuff such as taking information from the mailing lists and making sure that it finds a home in the manual.
<zakg> As time passes, I want to start working on the harder stuff that requires planning.
<werdna> nod
<zakg> I also want to make sure that I'm helping and working with the other folks who document things.
<-> Tiptoety is now known as Tiptoety|away
<Nikerabbit> zakg: I like the idea of concentrated effors on small topics
<Nikerabbit> also some huge colored table which turns from red to green as things get better is also higly motivating :)
<zakg> Nikerabbit: That can be arranged. ;)
<Nikerabbit> I have a general feeling that we don't do enough things together
<Nikerabbit> some things go slowly because nobody voices their opinion and single person doesn't dare to go forward without those
<werdna> oh noes, zakg is going to hijack the Hackaton for documentation updates :P
<werdna> (I'm only kind of joking)
<zakg> Nikerabbit: Given that I've done much of this work alone, I'd tend to agree. :)
<guillom> the hack-a-ton is going to become a doc-a-ton? :)
<zakg> Nikerabbit: We need to change that pattern. It's a wiki, fer Zarquon's sake – what's the worst that could happen?
<siebrand> werdna: that's not a bad idea. Having a 15 min. introduction and spending another 105 mins. on making actual improvements with a group of interested devs may render a lot of result.
<zakg> werdna: You are safe from me hijacking things. I can't get into the USA yet - I have to fill in many papers first. It's a long story.
<siebrand> even better. An onlyline Doc-a-ton.
<siebrand> "online doc-a-ton" even
<zakg> I do want to do docs sprints. We can cover a lot of ground in a group – especially if we focus on getting the knowledge into the wiki rather than worrying about how pretty it is.
<-> ^demon is now known as ^cemon|away
<-> RoanKattouw is now known as RoanKattouw_away
<-> ^cemon|away is now known as ^demon|away
<ragesoss> As a total code noob who started trying to learn PHP to tinker with MediaWiki, I'll just echo the bit at the start about collecting and highlighting a set of well-documented extensions that use a wide variety of hooks and API features. It was hard for me just to find any example (much less a good one) of how to do something like what I wanted to do, although I did eventually.
<zakg> ragesoss: I hope to encourage the docs writers to have a strong focus on using examples (http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan#Writing_Style)
<werdna> zakg: perhaps somebody else will hijack it on your behalf :-)
<zakg> werdna: yay! :)
<zakg> So. The approach that I'm taking is very community-centric. I've got my plan and ideas. I'm going to try them out by using them to serve the community, and I'll see what people like and don't like. It should be a collaborative, fluid (though at times the fluid may be tears) process.
<zakg> We've got a few minutes left in the formal session, but I'm happy to keep chatting as people are interested.
<zakg> Before this session closes, is there any key issue that anyone would like to raise?
<zakg> I'll do this again in 12 hours and most weeks afterwards.
-*- zakg waits a moment
<zakg> Ok. Thank you for coming and chatting with me. Feel free to suggest topics that need documenting and documentation pages that need help.
<werdna> thanks zakg
<zakg> If you run across docs issues, please send them my way - esp. via public channels.
<Nikerabbit> thanks
<Nikerabbit> resource loader is a new feature that should have good docs
<zakg> ... and if you haven't, please review http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
<werdna> it's really great that somebody's looking properly into the state of doc
<Nikerabbit> zakg: what is your timezone?
<zakg> UTC-7 / PDT/ PST
<siebrand> zakg: question on http://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan#Process_Flowcharts
<siebrand> you describe several 'flag' events.
<zakg> werdna: It's been fun and a nice change. I've spend too much time in startups lately.
<zakg> siebrand: ... and I need to expand that.
<siebrand> I may have read over it, but it's not (yet) clear how/where to flag, right?
<siebrand> bugzilla seems obvious, but not to the casual contributor/developer, maybe.
<zakg> siebrand: Right. I don't know if we would use Pending Changes, templates or ...
<zakg> I'd like it to be really simple for people to use - even casual visitors.
<zakg> As you write, bugzilla (unless we do some integration work) isn't that tool.
<siebrand> pending changes probably requires a confirmed account (someone who can confirm that?)
<siebrand> template work pretty well, but requires some process knowledge.