Jon Stephens,
MySQL Documentation Team
Stockholm

I’m also use Wikis heavily, and I even believe that using Wikis for documentation purposes is superior to any other format — under the premises that you know what you’re doing. If Wiki was the best format for all sorts of docs then all other formats would have died already.

I was referring specifically to the experts/changes ratio. That applies to both software and documentation, but I think it’s even more relevant for documentation. With small docs (or likewise not very complex software) you’ll have very few changes/edits. This makes peer reviews easy. With huge docs (or vastly complex software), tracking and reviewing changes becomes much more time-intensive (exponentially, from my experiences).

Wikipedia is a great example of “not too complex” (although huge in its entirety) and a healthy experts/changes ratio at the same time. Therefore, it works great. On the opposite end, small docs about highly specialized software often work well, too, because there’s just a small group of experts who do the edits (spammers aside ;-)). Open Wikis are a problem for things in between those extremes, when stuff is complex and changing a lot, because experts are rare, and thus peer reviews aren’t “cheap” to get.

The way to address that problem regarding “in between” software development and documentation is to have closed user groups who can contribute freely. In the end, that’s how projects like Apache, PHP, or Linux work: They have “core groups” who decide on what’s in and what’s not, and I couldn’t simply become part of the Linux kernel core group just because all my computers run on Linux.

With MySQL software and MySQL docs I think we should go for that “closed user group” concept. We’re not there yet, but we’re certainly moving into that direction. (As for translations of the docs, we’ve been giving SVN access to translators through WebDAV for years.) Once there, we can then start opening up the docs (WRT write access) to a wider audience.

As a side point to this side thread, the man pages of the MySQL Manual are already free: They’re published under the GPL. This might serve as an indication that we’re not “closing up” the MySQL docs just because we think “closed” docs are a good idea by itself.

You said: “As for free editing: … one third of those comments are wrong or misleading, … With direct editing, the quality you’re praising would diminish within months.”

I don’t claim that a wiki or other free-for-all system would be better. I think the things you worry about might happen. But, it doesn’t have to be as convenient as clicking the edit button. A SVN or other repo with commit rights might work OK.

I’m not convinced that even a wiki wouldn’t work out. If I were you I’d be afraid to try it too. But you never know. I mean, a lot of smart people said distributed software development couldn’t work too, and now we have GNU/Linux. Intuition isn’t always reliable.

In the end this post wasn’t really about that, but it’s an interesting side thread. My point is that free redistribution of the manual (and man pages, etc) is currently impaired.

As for the latter, people are already doing that, but since the Manual is under regular copyright there are legal ways to address that. With a free license, we couldn’t do anything. The MySQL Manual ranks high on Google among the most popular tech pages on the Web, and that attracts a lot of copycats who find it easy to earn money through ads by putting a copy of the Manual on their websites (and, of course, never updating it). One of our daily tasks on the Docs team is pointing out to users complaining about “our” docs being badly outdated that, no, those aren’t *our* docs.

As for free editing: You’re saying that the Manual is quality software documentation (thanks!). Now imagine every user who’s currently limited to adding a user comment would be able to edit the Manual. About one third of those comments are wrong or misleading, and another third is more or less off-topic. With direct editing, the quality you’re praising would diminish within months.

People keep suggesting that putting the Manual into a Wiki would address those concerns at least partially, even if the Manual were under a free license. Well, apart from the fact that we’d lose much of what makes the Manual convenient for users and developers (e.g. the multitude of formats we deliver, or the flexibility to output much more than just text), there are simply not enough subject matter experts around who could do the necessary peer reviews, and the quality of Wiki docs is directly linear to the experts/changes ratio.

Having said that, we keep thinking of making it easier for people (like you :-)) to contribute to the docs. In fact, we have concrete plans for this in place. Now, please ask someone to double the headcount of my team, and we’ll implement these things before this year is over. ;-)

-Stefan, MySQL Docs team