Why I Don’t Do EPUB

Lots of work for little benefit

Antti Hietala
Jul 15, 2014 · 6 min read

I write technical documentation for open-source software. The content is available publicly on the Web. When asked to provide the same content as ebook for offline reading I weighed the pros and cons of EPUB production and finally decided against the idea. Here’s why.

The case for ebooks

Offering content in ebook format makes sense when:

  • You are a print book publisher. Today, it is mandatory to offer electronic versions of print titles to stay in business. Amazon sells more Kindle ebooks than print books. The consumer expectation is clear.
  • You charge money for your content and want to find a new distribution channel. This is the situation magazine and newspaper publishers find themselves in. Ebooks may help keep current subscribers pinned or attract new eyeballs.
  • Your content is long form. Reading multi-page content on a desktop or mobile device is not ideal. Readers may prefer a device that is designed to make longer reading comfortable.
  • There is no extra effort involved in producing ebooks, so why not?

The first three cases don’t really apply to my content. The documentation I write is already on the Web, for free, and the pages are short.

But the fourth case might be true. I was curious. If producing an EPUB does not cost any extra time or effort, why not give it a go?

Collaborating in a wiki

First I need to explain why I write technical documentation in a Confluence wiki. There may be other tools that are better at producing EPUB that I may be shutting out.

Wiki is my tool of choice because I don’t write alone. Many users contribute to Magnolia documentation. Since most contributors are not technical writers I need to make contribution very easy for them. Wiki is a fantastic collaboration tool to beginners.

Any unnecessary obstacles such as forced structure (DITA) or formatting conventions (Markdown) stand in the way of getting content written. A casual user who wants to contribute should be able to just start typing. I will take care of the formalities. Wiki is great for that. Collaboration and ease of use are killer features that make an open documentation project work.

Success criteria

I estimated that for EPUB production to be worth the effort, the following criteria would have to be met:

  • Self service. Users should be able to export content from Confluence to EPUB on their own. I don’t want any part in it. I prefer to spend my time figuring out what content users need and writing it. Fighting with output formats? No thanks.
  • Measurable. I like to know what pages users read, even offline. Are certain pages read offline more than others? What search terms are popular? Google Analytics already tells me that for online docs. Is there a way to get similar analytics about EPUB usage?
  • Feedback. Users ask questions and comment on the documentation. This two-way relationship results in better content. A clear feedback channel is essential for continuous improvement. Is there a way to get feedback through EPUB?

Scroll EPUB Exporter plugin

Since I write content in a Confluence wiki I downloaded the Scroll EPUB Exporter plugin. The plugin is provided by K15t Software and available on the Atlassian Marketplace.

The plugin is easy to use and the output looks professional, even without custom theming.

My first impression was positive — this could actually work. The plugin even adds a new menu item in Confluence that allows end users to export EPUB on their own. That was a key feature in meeting the self-service criteria.

However, the plugin has two unsolved issues that erode its usefulness for me.

1. Exporting pages per label

One of the most popular topics in Magnolia documentation is the Technical Guide. It’s not a single page but a collection of pages that help newcomers understand and evaluate the product. The technical guide is also the most relevant piece for offline readers.

While each topic in the guide is fairly short, together they make long-form reading. Users should be able to export all the pages in the guide to EPUB in one go.

The Exporter plugin can export multiple pages per label but it assumes the labeled pages reside under the same parent page. In my case they don’t. The technical guide topics are spread all over the Magnolia documentation wiki space.

2. Ordering pages

There is no way to influence the order in which pages are exported.

The technical guide topics should be read in a particular order. This is somewhat rare. Typically readers pick and choose the topics they want to read. As a writer, I have little influence over the reading order and mostly that is fine. However, anyone new to the product really should read the technical guide topics in the order I put them. Basics first.

The EPUB Exporter plugin unfortunately exports pages in the same order as they are in the page hierarchy. The first page in the hierarchy becomes the first page in the EPUB. This is not how the technical guide topics are ordered in my wiki space.

To their credit, the K15t Software support team was responsive and helpful. While they could not solve either issue on the spot they suggested I vote up the tickets:

  • VSN-1026 Page Maps (aka Topic Maps)
  • EXP-347 Let Users Define Export Structure.

Due to these issues my “self-service” criteria was only met partially. While users could export single pages to EPUB on their own, any ordered collection of topics such as the technical guide was going to have a weird order.

Analytics

I use Google Analytics for online documentation. But offline I don’t know who reads what. Can EPUB report analytics?

Ebook analytics packages such as ePubDirect focus on reporting distribution, basically how many times an EPUB is downloaded. While interesting, downloads does not help me write better documentation. I need to know usage-specific statistics such as what are the most-read pages and what search terms are readers using.

I looked for a way to embed analytics into the EPUB itself. A company called Hiptype was after the same thing in 2012:

Hiptype analytics idea was built around inserting a snippet of code into ebooks. When you read the ebook that snippet of code would track what you were doing and send data back to Hiptype’s servers, where it would be collated and served up to the relevant publisher.

Unfortunately, Hiptype shut operations down due to lack of interest from ebook publishers:

The snippet of code initially only worked in iBooks because that platform supported Epub3, while getting similar data out of a Kindle or Nook ebook required the cooperation of Amazon or B&N. Neither liked the idea.

So that killed my criteria #2: Measurable.

Feedback

The final success criteria was the ability to get reader comments from the EPUB. Such functionality does not exist in the EPUB format natively. It’s just a content format. The devices don’t seem to have a standard way to collect and send feedback either. I kind of expected that the device could capture the page title and let the user send an email to an address I provide in the EPUB.

The K15t support team recommended that I add a link in the EPUB that takes the user back to Confluence for commenting. Sending readers back to online docs would be an extra hoop but the recommendation was reasonable.

Criteria #3 Feedback was kind of solvable.

Summary

With two out of three criteria unmet, I pulled the plug on the plugin.

Producing EPUB would mean extra work for little benefit. For readers who still prefer offline, Confluence allows you to download individual pages as PDF. This is out of the box functionality. The PDF format is widely supported by e-readers and requires not extra effort from me.

I hope my experience helps you make a decision if you are weighing the options. If your documentation is already in a Web-native format and publicly available, producing an offline format may not be worth the effort.

Technical Documentation

Best of developer docs

    Antti Hietala

    Written by

    Product manager, average skier, awful fisherman. Yes-hat wearer. Fan of hot glue.

    Technical Documentation

    Best of developer docs

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade