Gentlemen prefer PDF, according to Tim O’Reilly’s data from Rough Cuts five years ago. At OpenStack we see some preference for PDF, though there are three times as many visits to the HTML version of our Compute Admin manual. Still, the PDF version of the guide is downloaded about five times a day. I do believe that gentlemen prefer PDF or some sort of book-like reading material. When asked, readers cite portability and search scope as two benefits to the form. However, as David Cramer, our doc tools developer put it at our recent hackathon, “PDFs are like cement.” With the boom of mobile and tablet screens, a stretchy and flexible screen-reader format like epub fills a need – we need content that works well on the 200 plus devices that fit into one hand.
So on 11/11/11, in the Austin Rackspace office, we did some hacking to be able to create epub output from our DocBook source files. I blogged about it for the OpenStack Planet blog from my blog, DocBook, ePub, Hackathon, what more could you ask for? prior to the event, talking about some of our prep work.
I’m pleased to show you the results – we did get output for epub and also tested the Mobi output on a Kindle, all in one day, with a team of about seven hackers including developers, writers, and testers.
We first tested the process using built-in epub transforms that ship with Oxygen, our XML editor, who supports open source projects like OpenStack by donating licenses to documentation contributors. Thank you Oxygen! We were able to use that output to start testing. Here’s our white board with the list of bugs. 
While the writers and testers were hacking on output, programmers were working on ensuring we could get the epub output through Apache Maven, our build tool. By the end of the day, we could output epub through our automatic build process also!
As happens with hackathons, there’s some cleanup work to do – for example, our neat-o dynamic SVG cover page that takes in variables like the book title doesn’t output a cover for the epub. Also, most “real” epub output workflows convert tables from text to image (I know, crazy huh, when you think about the loss of search capability), but the tables in epub output act a little funky when resizing. Also, mobi, the Kindle format, has a problem with the way lists are marked up, but these are fixable and on the bug log.
I haven’t decided yet whether the epub output is high quality enough to offer it for download for every book on the OpenStack docs site, nor do I know if there’s much demand for the output, but I’d like to offer the OpenStack Starter Guide as an epub download. The team at CSS OSS works hard on this content, and I’d like to see it get spread onto many devices. Let me know how well it works for you and if you think epub has a place as a regular output for OpenStack documentation.
Leave a Reply