We launched the all new Passenger Docs last week, and were eager to hear your feedback. @deoren asked us on Twitter if we would consider making the docs available offline, too. That's a great question, and one we were dying to answer for ourselves as well.

The most popular format for offline docs is the ePub format. Rendering an ePub was something neither Floor or I had ever done. And while we were mostly worried about the maintainability and navigation of having the docs offline (the Docs rely heavily on filters), we were also curious to see if we would be able to work around this. This article aims to share some of the steps we've taken in helping you set up your own ePub docs.

Tools and specs

One of the biggest benefits of having documentation available as an ebook is that it is available on the go. No internet connection needed. One of the biggest drawbacks on the other hand is that each new change to the documentation requires us to release a new ebook. This is done through authoring a new ePub each time.

An ePub is nothing more than XHTML & CSS, with some conventions on how the documents should be organized. Since our Docs are basically nothing more than HTML & CSS (and a fair bit of Javascript), you'd be inclinded to think that converting one into the other should be fairly trivial.

We use Middleman to generate the HTML representation of our developer documentation. Even though ePub as an output format is not supported by default, the ebook-example.middleman provided some pointers on how to proceed. It suggests to create a minimal layout, that is valid according to the ePub specs. Chapters can be written in Markdown and put in a manuscript folder. All chapters are then rendered as partials in the layout. This results in one large HTML file with all the desired content.

To generate the ePub file itself the eeepub gem is used. This gem takes the generated HTML file as input, and converts it to an ePub file. This involves taking the HTML file and wrapping it in XML container files that are required by the ePub format, and zip it. The gem does not validate the input files, or the outputted ePub file. It will happily generate a broken ePub that will raise errors upon opening, or fails to open in the first place.

Our first few attempts resulted in broken epubs that sometimes wouldn't even open. Obviously, some form of validation would be required, lest we end up shooting ourselves in the foot. And to that end, we decided to bite the bullet and installed Java to be able to use W3C's open source epub validator.

The experiment

Our new documentation consists of three main parts, Tutorials, Advanced Guides and the Configuration Reference. We decided to get started with the latter, because it is the most straightforward part. It consists of three huge pages - chapters if you will - listing the configuration options for Passenger for each of the integration modes. The tutorials and advanced guides follow more of a wizard-style format and seemed less suited for an ebook in their current form.

We succeeded in converting the huge HTML file containing the config references to an ePub file. The validator however seemed to be raising errors like there was no tomorrow. Even after making some small manual fixes in the source file, we were unable to generate a valid ebook for our configuration reference. What could be the cause of this?

The outcome

The Docs' index pages are void of content by design. Instead, the content is hosted as partials in localStorage, and pages are filled based on the user's selection (for example: installation of a Python app, using the Nginx integration). The redirects are all Javascript driven, and as you can imagine, ePub doesn't play well with so many variables. The long list of HTML errors the validator returned seemed to suggest that we should have opted for an entirely different structure. One that factored in the possibility of viewing documentation offline from the get go, both in structure and technology.

Both the old documentation (the Library) and the new documentation (Docs) were designed to feel more like a web-app than a book. As such, their format doesn't really lend itself well for reading in sequence, as they encourage people to view more information via cross-references and links. Needless to say, this doesn't really jell with the book-paradigm.

If we somewhere in the future would consider releasing an ebook of the docs, we would first need to restructure our content to make it fit the book-paradigm. Aside from that we would need to remove all unnecessary HTML, Javascript and CSS from the output. It can definitely be done, but it will require some serious effort.

So what did we learn from all this? Well, if you are considering revamping your docs, and you want provide it as an ebook as well, you should carefully consider how you structure your content from the onset.

Still want to view Passenger Docs offline?

Did you click this link hoping to find out how to read our doumentation offline? We're looking into other ways to make the Docs portable. If you might have any suggestions we'd love to hear those!