We’ve had a bug about documentation in Mediawiki open since August 10, 2004. In fact, it was the first bug ever filed when Mediawiki moved over to using Bugzilla. In the past 5 years, MediaWiki has grown in quite a few ways. There’s more developers than ever before committing code faster than ever before (a few days ago, we averaged like 100 commits per day for like 2 and a half days). So much is going on, that Brion’s trying to clone himself.

Are the documents any better now? I would certainly say so. We’ve gotten MediaWiki.org in the meantime, the Manual namespace has grown to massive proportions and a well-written Public Domain Help namespace has been fleshed out. We’ve got Doxygen (think Javadoc) auto-generated docs available. In many ways, we’re so much closer to fixing bug 1 now than ever before.

Is it fixed yet? No. It never will be, and that’s just the nature of software development. We’re never as documented as we could be, and it’s nearly impossible to catch up unless you halt all development until the docs are finished. Hopefully though, we’re getting better. Simple things that committers can do is adding their Doxygen docs. This has immediate benefits for other coders who want to understand what your code does, as well as help keep the auto-generated class docs up to date.

I brought up the issue of QA with our docs about a month ago. It has become nearly routine that users will come into #mediawiki on IRC and ask us a question based on what they read in the documentation. After discussion, it becomes obvious that the docs are wrong. The docs get fixed, and the user is on their way. However, this issue shouldn’t happen to begin with! After some pestering, I finally got Brion to install FlaggedRevs on MediaWiki.org so we can hopefully get our docs under control. With this in place, it will be much easier to tell what documentation has been verified for accuracy, and we can present this to our users.

Resolving bug 1 takes a lot of work :)