MySQL manual gets improved searching
Hooray! The MySQL reference manual has a new search system. It now uses a Google Appliance and the results should be a lot better. The old system was not very helpful. It used to break config variables into multiple words and search on them individually and give a billion results I didn’t care about. I’ve just tried to search for some things like key_buffer_size and got results I think are very useful.
I love the MySQL manual. It is a great example of quality software documentation. As someone recently mentioned, it is not released under a Free license though — that would be a great improvement, too!
When did this change happen, by the way? Maybe it’s been there for a while and I just missed it because I grew accustomed to using Google search instead.
Edit: I actually would suggest a change to this search, too. It’s the same change I have suggested in the past: put the document title in front of the manual’s title. Instead of “MySQL :: MySQL 5.1 Reference Manual :: 7.4.6.6 Restructuring a Key …” I would rather see “Restructuring a Key Cache :: MySQL 5.1 Reference Manual”. (Note that the title gets truncated as-is, and it’s hard to see in the browser’s titlebar/tab/system taskbar).
Thanks for vote of confidence!
We have some other improvements planned for the searching that will make it even easier to find information on specific functions and SQL statements (among other things).
There will also be better linking and meta-information about individual pages and other places you can go for more information.
On the title naming issue, the Docs have to fit in with the rest of the website, hence the current naming layout, but it’s certainly something I’ll think about.
MC Brown, Technical Writer@MySQL
Martin Brown
28 Jul 08 at 11:20 am
I miss the ability to add search terms to the mysql.com domain in the browser address bar. For example, you used to be able to search on keywords by typing something like this: http://mysql.com/SELECT
Doug Lane
28 Jul 08 at 12:53 pm
Doug — you can still do that…..in fact, clicking on your link works as expected.
Sheeri Cabral
28 Jul 08 at 1:38 pm
I realized that after I posted (duh, I should have checked). Last week, though, I was trying this:
http://mysql.com/delayed_queue_size
and it did not work. I’m glad to see the feature is still there.
Doug Lane
28 Jul 08 at 1:57 pm
I would love if they could do something like http://www.php.net URL Documentation style.
Its little difficult for MySQL, but they can work on that idea.
Ruturaj K. Vartak
29 Jul 08 at 1:27 am
Baron, one of the biggest problems I have always had when using the MySQL manual is finding information specific to the table type I am working with. For example, if you read something like the alter table page, it is littered with little notices about “on this table type, you will see x behavior, but on this one you’ll see something else”. The problem goes both ways for me… I’d rather cut out the clutter for things I am not interested in, and also sometimes am left wondering how something works on secondary table types (like merge tables for instance). This seems like a hard problem to solve (I’ve thought maybe the solution is to rewrite the manual as seperate engine specific manuals, but thats a lot of work), I’m curious if you have any thoughts on it?
xzilla
31 Jul 08 at 11:05 am
I’m sure the MySQL docs team have thought about this a lot, and I will let them comment.
Xaprb
31 Jul 08 at 1:47 pm
xzilla, thanks for pointing this out. In fact, this is a complaint I haven’t heard before, but yet it’s similar to other issues people are having with the docs:
- Operating system: MySQL runs on many operating systems, and on each it runs a little differently. This is particularly true for things like installation, building from source, importing/exporting data, etc.
- Version: Users have been asking for minor version-specific manuals (e.g. one manual for 5.1.25, one for 5.1.26, etc.) for as long as I can think of it.
Splitting up the MySQL Manual to become operating system-specific, minor version-specific, or even storage engine-specific wouldn’t be too hard (at least not for future editions of the Manual), but maintaining such a multitude of versions/flavors of the docs would be a nightmare.
I could get into very much detail, but instead let me just point out two aspects:
1. The MySQL Manual was once one big thing covering every single MySQL version. This became increasingly confusing when we released MySQL 5.0, so we split it up into major version-specific manuals. You won’t believe how many people hated us for doing this, and they all had very good reasons why the MySQL Manual should have been kept as one big document.
2. Imagine we had split up the MySQL 5.1 Manual so it would be specific to operating system, version, and storage engine. Roughly, we’d have ended up with 20 * 25 * 10 = 5000 individual manuals, just for MySQL 5.1.
Splitting into physical documents isn’t a sane solution, and marking up the DocBook XML sources so we could generate xyz-specific manuals is far less trivial than it might sound. You can’t “IFDEF” docs more than superficially; after all, the audience isn’t machines but rather human beings. :-)
That said, at the MySQL Docs team we keep thinking about those issues, and we’ve been implementing ways to address them. One of the results is the Server Version Reference you can find under http://dev.mysql.com/doc/mysqld-version-reference/en/index.html. At some point we’ll expand that reference to cover more than just versions, and also we’re adding more and more overview tables to the Manual itself, to make it easier to look up features, limitations, etc. One example of this, relating to storage engines, is here: http://dev.mysql.com/doc/refman/5.1/en/storage-engine-choosing.html
-Stefan, MySQL Docs team
Stefan Hinz
1 Aug 08 at 5:56 pm
Baron, I’m not sure that putting the MySQL Manual under a free license would be a good idea. If we did that, anyone could edit it freely, and publish it freely on the Web.
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
Stefan Hinz
1 Aug 08 at 6:33 pm
Stefan, thanks for your thoughtful reply. I am not sure I agree with everything you said. I don’t think I have any grounds to say I’m right and you’re wrong, I’m just unconvinced.
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.
Xaprb
2 Aug 08 at 4:22 pm
Baron, don’t get me wrong. I’m a fan of open source software, and particularly of open development models. I strongly believe open source leads to better quality.
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.
Stefan Hinz
2 Aug 08 at 6:20 pm
Thanks a lot Stefan, and I’ll keep my eyes open for these changes you hint at. Let me know if/when you do decide to open up to outside committers. I can’t promise anything, but in principle I’d like to help.
Xaprb
2 Aug 08 at 6:51 pm
One issue that many people (including some who work for MySQL/Sun) don’t stop to think about is that the Manual and other MySQL documentation is also part of our paid support offerings; we have legal/contractual obligations to provide accurate (or at least “best-effort”) docs to customers. Allowing just anyone to make edits to the Manual with no controls and possibly to add incorrect information or to modify existing content so that it’s wrong could itself cause problems for our Support Team and even get us into big legal trouble with our paying customers.
Jon Stephens,
MySQL Documentation Team
Stockholm
Jon Stephens
11 Aug 08 at 4:41 am