We got an interesting question on the documentation list the other day, which basically asked if we provided a service that listed changes to specific pages in the manual.

While I like the idea of such a service, the mechanics of making such a service work are very difficult. To start with, and to re-iterate something I have to explain again and again:

the MySQL documentation is rebuilt up to 10 times *every* day

We don’t have set schedules for when we release changes. We don’t bundle changes up and then produce a new reference manual on a set day of the month, or week. If I make a change to the documentation right now, there is every chance that you would see that change in the live docs at http://dev.mysql.com/doc within 3 hours, and for the PDF format, possibly even within the hour.

Yep, it happens that quickly. And that happens every day of the year – even at weekends and holidays.

It’s also worth pointing out some of the statistics of the documentation to help explain why such a system might be impractical, but not impossible.

Our current mysqldoc repo, in existence since we made the move to DocBook, has just hit revision 14955, which means over the last 3 years and 7 months, we’ve made on average 11.45 commits every single day. On some days, we make many more than that, and sometimes those changes can be minor (like a typo correction), and other times they will be a huge reorganization or rewrite.

But there-in lies the other problem with any kind of monitoring of changes – our documentation is big and complex. Any ‘page watcher’ to notify you of changes would be limited by the fact that we split the reference manual into just over 2000 different HTML pages. And of course we do that for each manual (4.1, 5.0, 5.1, 5.1-maria, 5.4, and 6.0). For those keeping score, that’s about 12,000 different HTML pages for the reference manual alone.

If you want to talk printed pages (and why not), the Letter-sized PDF manuals for the main documents in English (reference manuals, GUI docs, the MySQL version reference (15 docs) constitutes about 17,300 pages of content.

We actually create 91 different documents from our English language repository, and 234 documents across all languages in up to 14 different output types (PDF, HTML, texinfo, txt, etc).

So to return to the original question, would a page monitoring service be possible?

Probably.

Would it be useful?

I’m in two minds about this. I can see the value of having a way to see changes, but if what you want is to be able to monitor changes in behavior, then most of the time this is documented in the changelog, and we have a number of different outputs available for viewing the changelog information in more useful ways.

Other, more minor changes, and in some case major rewrites wouldn’t feature in the changelog (because they don’t relate to a change in the product we are documenting). Whether you would find such changes useful is up to you. A rewrite normally means we’ve decided to change the content to make it clearer, or we’ve re-organized the information to make it flow better. Again, it doesn’t necessarily constitute a change to the product that wouldn’t otherwise be in the changelog.

Would it be practical?

Probably not – the sheer size of our documentation would mean that just providing the data on the changes would probably double the number of pages and information, and it wouldn’t always be clear whether the change were just a typo correction or a major rewrite. And tracking the changes if we change a page ID (which we do, from time to time), would it difficult to correctly identify changes across different pages that really had the same content.

Of course, I’m open to suggestion here, and we are doing things to further improve and enhance the content, and maybe this is something we will consider. But I’m open to input on whether this is needed.