By Scott Prentice | Senior Member
You’re probably quite familiar with eBooks and have heard that they are taking over the publishing industry. What about the documentation you create? Is it time to deliver that as an eBook? If so, you’ll need to know where to start and what’s involved.
But first, what exactly is an eBook? In the most general sense, an eBook is just a book that you can read on a device or computer. An eBook may be available in different formats and reading it may require the installation of a proprietary application. Unless you have a specific requirement to use a certain type of eBook, it’s probably best to go with the EPUB standard.
An EPUB can be read on virtually all devices and platforms, from desktops to laptops to tablets and other mobile devices. As the content provider, you create the EPUB file, and the end user reads it in an eBook “reader” application or device. Most dedicated eBook reader devices will accept an EPUB file, with the notable exception being the various forms of Amazon’s Kindle. Luckily, it’s not complicated to convert an EPUB file into a format that’s acceptable to a Kindle (MOBI or KF8 formats). We’ll discuss that more later.
The main rationale for choosing an eBook format is typically based on the intended accessibility to your documentation. If you are making the documentation freely available, EPUB is the way to go. If your documentation is only available to a restricted audience and requires tight control, a proprietary format and reader may be preferable. However, DRM (Digital Rights Management) may be built into an EPUB which can restrict it to specific reader devices, making this an option for restricted delivery as well.
Content in an eBook is intended to be re-flowable to fit the constraints of the rendering device or application. This is similar to the way simple content in a Web browser will adjust to fit the width of the application window. Most eBook readers work on a screen-based “paged” format, meaning that the number of “pages” in the book will vary depending on the size of the device or application window and the size of the font. Typically the font characteristics (style, size, color, etc.) are user-definable. Because of this, you can never expect that a specific passage will be on the same page in the same eBook in different readers.
It may seem that the paged reading model would have implications on the type of content that’s best suited for an eBook. It does work especially well for “guides” or conceptual information which assume that you’ve read the content in a particular order. But because most eBook readers provide a table of contents as well as search functionality, you can also drop in to a specific concept in the middle of the book, making it useful for reference material as well.
I like to think of EPUBs as making your documentation “ultra portable.” In fact, there’s no other delivery format that makes your documentation available on more devices or in more situations. If your users might benefit from having easy access to your documentation at all times, it’s worth considering the EPUB format.
The EPUB Format
The EPUB format has evolved over many years. The specification is maintained by IDPF (International Digital Publishing Forum). EPUB 2.0 became an official standard in September 2007, which superseded the older Open eBook standard (OEB) from 1999. EPUB 2.0.1 was approved in May 2010 and EPUB 3.0 was approved in October 2011. Since that time the EPUB 3 Fixed Layout format was added in May 2012, and the EPUB 3 Indexes format was added in January 2014. An EPUB 3 Dictionaries working group is in progress. For the latest information, visit the IDPF website at www.idpf.org.
The underlying technologies of the EPUB format are XML, XHTML5, and CSS. The EPUB format supports images, standard formatting, and linking. EPUB 3 brings in a host of features supported by HTML5 and CSS3 such as multimedia, scripting, MathML, SVG, and better font and page layout. However, keep in mind that there is often a disconnect between the features defined by a specification and how those features are supported by “real world” applications. This is very much the case with the EPUB format and the features supported by eBook readers. It’s important to be aware of what you may be able to do in the future, versus what’s reasonable to expect today.
An EPUB is technically just a “zip” archive of the various content, navigation, and metadata files. In order to overcome the shortcomings of EPUB-creation tools, it’s often necessary to extract the contents of the file to make minor adjustments.
Creating an EPUB
Most of the information you’ll find on the Web about creating EPUBs focuses on books that are produced for retail purposes, typically written for one audience and one output type. In the tech comm industry, we often produce multiple versions of a document and deliver it in multiple formats. It’s not likely that you’re going to stop producing, HTML, PDF, and Help formats and focus solely on eBooks. You’ll probably just add one more deliverable to your current list.
Authoring tools such as Adobe InDesign or Apple iBooks Author are used for authoring content specifically for export to EPUB. If you are authoring specifically for EPUB, these may be a good choice of tools, but it’s more likely that you are authoring for multiple formats rather than focusing on just one.
If you’re currently producing some form of online Help, the tool you’re using to produce that output may also support the EPUB format. Even though EPUB 3 is the current specification, many of the tools still produce the EPUB 2 format. This is typically fine because EPUB 3 reader applications will also handle EPUB 2 files. Give it a try. Use the default “export to EPUB” option and see what you get. After exporting to EPUB, view it in a desktop reader as well as in a reader on your mobile phone or tablet. You’ll see that some features look better than others (tables are typically the biggest problem for small screens).
Regarding the EPUB 2 versus EPUB 3 issue, at this time most readers don’t support the EPUB 3 specification well. You’re best off using EPUB 2 or very basic EPUB 3 files. If you really want to take advantage of some new EPUB 3 features, your eBook will be limited to fewer readers’ applications. Be sure to test on specific readers and make the list of supported readers available to your end users.
The most common problems are caused by excessive formatting. Some tools try to emulate the formatting in your source document, which is typically not what you want on a small screen. There will often be an option for assigning alternate formatting to the source document’s styles. Wherever possible keep the formatting simple. Remember that the end user has the ability to assign fonts and coloring based on their needs. Don’t work against them by creating your own “fancy” formatting.
It’s important that your source files follow good authoring practices of using named paragraph and characters styles. When you apply overstyling to a word to diverge from your named styles, that styling is typically passed on to the EPUB content and cannot be controlled through CSS.
After exporting to EPUB, open it up and look at the markup in the HTML files created by your tool. Wherever you see “style” attributes in the HTML files, you will not be able to control that formatting via CSS classes. These style attributes may also cause problems for different eBook readers. You’ll find that an EPUB with no style attributes will look best on more eBook readers.
EPUB-Creation Tools
It is important to have a tool that lets you open up an EPUB and look inside. When something doesn’t look right, this is often the only way to determine what’s gone wrong. None of the EPUB-creation tools do a “perfect” job. They will get you most of the way there, but you’ll typically need to do some tweaking to get things just right. The following tools will let you open an EPUB to review and edit the contents:
- Oxygen XML Editor
- BlueGriffon EPUB Edition
- Sigil (free!)
While many tech comm authoring tools claim to export “EPUB 3” files, they really aren’t taking advantage of the new EPUB 3 features. Don’t let that sway you when choosing a tool. The important thing is to use a tool that works well in your workflow. The following tools export to EPUB:
- Adobe FrameMaker 12 (EPUB 3)
- Adobe RoboHelp 11 (EPUB 3)
- ComponentOne Doc-To-Help (EPUB 3)
- EC Software Help & Manual (EPUB 2)
- MadCap Flare (EPUB 3)
- Webworks ePublisher (EPUB 2)
If you are using the DITA or DocBook XML models, you can use plugins and scripts to generate EPUB files. Additionally, extensions are available for FrameMaker and Author-it that allow EPUB export options.
- DITA Open Toolkit + DITA for Publishers plugin (EPUB 2)
- Docbook + EPUB 2 and 3, various options
- FrameMaker + ElmSoft EPubFm2 (FM 6-10) (EPUB 2)
- Author-it + ePUB Publishing Extension (EPUB 2)
After creating an EPUB, it is important to confirm that the file adheres to the specification. Do this with the epubcheck utility. Many authoring tools allow you to include this validation in the export process. If not, you can run it as a standalone tool. Most EPUB files will generate some errors or warnings; you’ll want to correct most or all of the reported issues. This is where you’ll need the tool that lets you open and edit the files within the EPUB.
While an EPUB that has reported errors may look fine on the eBook readers you’re testing, it may not look right on other readers. Also, if you plan to make your EPUB available through an aggregator site, they will typically require the EPUB to pass validation, error-free.
The Kindlegen utility, available from Amazon, generates a MOBI or KF8 file from your EPUB. Typically, simpler formatting in your EPUB produces a better Kindle file. In general, a MOBI file is created from EPUB 2 and a KF8 file is created from EPUB 3. Many of the authoring tools that export to EPUB will let you specify the location of the Kindlegen utility in order to generate these Kindle-friendly eBook files.
One more tool that’s useful to mention is Calibre. This is a bit like the “Swiss Army knife” of eBook tools. It provides numerous conversion options from many formats to many other formats. While this may be fine for testing and prototyping, I would not rely on this conversion to create a final deliverable. It also provides a reader application which can be handy and has an eBook management facility. Additionally, it provides a server application allowing access to the eBook library to anyone on your local network. This can be an excellent way to make eBooks available to others in your department or company.
EPUB Readers
In order to read an EPUB you need a reader application or dedicated device. It is important to test your EPUB on as many reader applications and devices as possible to ensure the best output. There are a handful of useful desktop reader applications (for desktop and laptop use), and many mobile applications. I maintain a list of reader applications (and other tools) at http://epubtest.com/resources.php.
Many of the dedicated reader devices produce desktop and mobile versions of their reader applications. For example, you can use a Kobo reader and you can use the Kobo desktop application or the Kobo mobile application. Same for Kindle and other devices. Unfortunately, you cannot assume that an EPUB will render consistently in these reader applications, even when created by the same company.
Figures 1–3 show some examples of the same page in the same eBook on different readers. You’ll notice that while the content is the same in all readers, the formatting of that content does vary. In particular, notice that the content that is italicized in the Kindle 4 Basic and the iPhone Kindle app is formatted as bold in the Galaxy Kindle app. (The figures use the “DITA Style Guide” by Tony Self, published by Scriptorium Press.)
The downside of having an “ultra portable” format is that it may require a lot of testing. This is another reason for keeping the formatting as simple as possible.
eBooks Are Here to Stay
If you produce documentation of any kind, it’s worth considering how your customers might benefit from having those documents available as eBooks. If you already produce HTML-based documentation, taking the next step to offer it as an EPUB is not a huge effort. Just remember to keep it simple. The best looking and most usable eBooks are those that apply the least amount of formatting.
Scott Prentice (info@leximation.com) is president of Leximation, Inc., based in San Rafael, CA. He provides consulting services for the development of custom online Help systems, EPUB development, and FrameMaker applications. He has been involved with DITA for many years and created the DITA-FMx plugin for FrameMaker. Scott was recently involved with the IDPF as an invited expert on the EPUB Indexes working group.
