Fwd: Farewell CHM, hello EPUB!

An interesting announcement here — I know we've had plenty of issues
with our CHM manuals, and maybe this is something we should consider.
I would be in favor of an epub format for our manual.


---------- Forwarded message ----------
From: Stefan Hinz <[email protected]>
Date: Mon, Sep 6, 2010 at 4:31 AM
Subject: Farewell CHM, hello EPUB!
To: [email protected]


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!

See also: http://blogs.sun.com/mysqlf/entry/farewell_chm_hello_epub

--
Cheers,

Stefan Hinz <[email protected]>, MySQL Documentation Manager

Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc

ORACLE Deutschland B.V.&  Co. KG
Registered Office: Riesstr. 25, 80992 Muenchen, Germany
Commercial Register: Local Court Of Munich, HRA 95603

General Partner: ORACLE Deutschland Verwaltung B.V.
Rijnzathe 6, 3454PV De Meern, Niederlande
Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
Managing Directors: Juergen Kunz, Marcel van de Molen,
Alexander van der Ven

--
MySQL Announce Mailing List
For list archives: http://lists.mysql.com/announce
To unsubscribe:    http://lists.mysql.com/[email protected]




-- 
Brett Bieber