Monday Sep 06, 2010

Farewell CHM, hello EPUB!

For a long time, the MySQL Documentation Team has been providing CHM files for most MySQL documentation we publish. Like many other formats, CHM-format docs can be downloaded from http://dev.mysql.com/doc. CHM (Compiled HTML Help) has been the de facto standard help file format on Windows since 1997, but the technology behind it is outdated and has all kinds of quirks. The successor format introduced with Windows Vista is AP Help, but it hasn't taken off in practice so far. So, with CHM being outdated and AP Help spread anything but widely, lots of vendors have started providing documentation on Windows in PDF or HTML format.

Building CHM-format documentation is a challenge of its own. I'll not go into details here, so let me just state that it requires a dedicated Windows box (or VM), and while it can be automated using Power Shell commands, there's no way to find out whether or not a CHM file was built correctly, except by manual inspection. This makes it different from all other documentation formats where technical QA is done (successfully) in an automated fashion.

With the increasing complexity and size of our documentation (the MySQL 5.1 Manual contains more than 1.6 million words now!), providing CHM has become more and more of a pain, because builds tend to break more often. We've stopped shipping CHM with the MySQL Server on Windows months ago because we simply couldn't guarantee that the help file shipped with the software would work. Also, we're running short on hardware resources, so we'd rather stop wasting the resources we have on building a format that's of limited use, anyway.

This is why we'll stop providing CHM for any of the documentation we publish.

To alleviate potential pains anyone might have with this decision, let me tell you that we've started providing EPUB-format docs. EPUB (see http://en.wikipedia.org/wiki/EPUB) is an open standard format for screen readers, mobile or not, and is fairly easy (and not resource-intensive!) to compile. Thanks to Lenz for suggesting to build EPUB!

Go to http://dev.mysql.com/doc to grab MySQL documentation in EPUB format. To read EPUB on desktop machines, I use a Firefox add-on, unsurprisingly called epubreader, which loads EPUB documents fast and renders them nicely. That said, please be aware that EPUB can't do anything about the fact that the MySQL Reference Manual is huge, so downloading it to a mobile device can take a while. The MySQL 5.1 Manual is currently a whopping 15 MB!

About

mysqlf is a common typo on the #docs IRC channel of the MySQL documentation team. It shows a high (some might say, dangerous) degree of identification with MySQL. Trying to pronounce it will probably result in tongue injuries.

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today