Creating ebooks using RoboHelp 9

The mass market for mobile content has been growing rapidly in recent years, so much so that you may be thinking about "mobilizing" your content. Why?

• Perhaps your audience uses smartphones, so mobilizing your content would fit with your audience's changing expectations.
• Perhaps your online Help is used in the field, where laptops are inconvenient.
• Perhaps you think that offering a mobile version of your documentation might differentiate your brand from your competitors.

For whatever reason, you're thinking about mobile. But how to proceed? This paper will help. It starts by outlining mobile "architectures", followed by an overview of a specific mobile standard called ePub, RoboHelp's support for ePub, and some best practices. The goal is to help you decide if it makes sense to create ePub-based ebooks using RoboHelp.

For this discussion, I'll postulate three basic mobile architectures, two of which, sites and ebooks, have a technical communication slant:

• Apps: These are what we expect to find on smartphones (iPhones, Android devices, and so on). Apps usually have minimal text, especially as compared to sites or ebooks.
• Sites: Web sites viewed through mobile browsers. They can be true web sites or online Help or doc in WebHelp or FlashHelp format created with authoring tools like RoboHelp. Online Help or doc sites are usually text-heavy but may also contain non-text elements, such as graphics and Flash movies.
• ebooks: Electronic books viewed on readers, such as Barnes & Noble's Nook and Amazon's Kindle, in formats such as ePub or mobi. They're also usually text-heavy but can also contain non-text elements.

Adobe added support for ePub in RoboHelp 8 and further integrated it into RoboHelp's interface for version 9.

The ePub standard comes from IDPF (International Digital Publishing Forum) at www.idpf.org. IDPF describes ePub as an "interchange and delivery format for digital books and publications…" At a basic level, ePub lets content reflow on different-size screens, but think of it as a way to put book-like content online. (I'll explain what I mean by "book-like" shortly.) Here's an example of an ebook, Alice in Wonderland, in Adobe's ADE (Adobe Digital Editions) reader.

In brief, ePub supports traditional online navigation features – tables of contents, search, and links, plus text formatting, graphics, and more. RoboHelp supports the current version of ePub, 2.0.1. For more information about v. 2.0.1, see http://idpf.org/epub/201 or, for a broader overview, see http://en.wikipedia.org/wiki/EPUB.

Note that the IDPF released the first public draft of the proposed ePub 3 standard on Feb. 15, 2011. (See http://idpf.org/news/epub-3-specification-public-draft-released) V. 3 is based on HTML 5 and, according to IDPF, supports "video, audio, scripting & interactivity, vertical writing and other global language capabilities… MathML, and styling & layout enhancements". The final recommendation is anticipated by mid-2011. V.3 will add the ability to create highly enhanced books for a wide variety of audiences. There's no telling when vendors will start to support it, but the added power and features make it worth watching.

ePub-based ebooks can be read on any native ePub reader for which an ePub plugin is available. The readers can be actual hardware, such as Nook, or software, such as Adobe Digital Editions or the FireFox ePub viewer plugin. There are many options, so you'll want to carefully define what hardware and software you have to support and whether their differences may affect your work. There's a list of readers to start with at http://en.wikipedia.org/wiki/EPUB#Software

Earlier, I said that ePub was "book-like." This was because it lacks three features that make it differ from what technical communicators are accustomed to for print and online publishing. Specifically, ePub does not support:

• Online glossaries: If your RoboHelp has a glossary, this lack of support will be an inconvenience if you single-source that project out to an ebook. If you don't, it's not a big deal.
• A-Z indexes: This is a big change from how books have been created for centuries. I don't know why IDPF did not support indexes. I imagine it's due to the growth of search in online content and the fact that many authors don't create indexes. Whether or not you agree with this rationale, the fact is that there's no index feature until and unless it's added in a later version of the standard.
• Context-sensitivity through map and alias files: If you use RoboHelp for online documentation, this is irrelevant. However, if you create Help, it may be a limitation. One can argue that it's irrelevant even if you do create Help since users won't run an application with online Help on an ebook reader. However, that's only true for a physical reader, as opposed to software-based readers like ADE or the FireFox ePub plugin. Basically, you'll have to decide what this lack of support means in your case.

With that, let's turn to the ePub support in RoboHelp.

RoboHelp 8 supported ePub but required authors to download two control files and set them up by working in code using the ExtendScript toolkit. Not difficult, although any code modification runs the risk of errors. RoboHelp 9 is more WYSIWYG, with Windows-style dialog boxes, shown below, replacing most of the hand-coding.

Configuration is pretty straightforward. For the initial setup, you define an XML output on the Single Source Layouts pod, download an archiver, and run a script. You'll do this once. After that, for each ePub project, you specify a graphic to use as the ebook's cover page illustration, define publishing metadata, such as the title, author, ISBN, and so on, and generate the output. Mechanically, it seems to work well. Here, for example, is the sample SalesBuilder-Help project, which I output to ePub without changing anything in the content or the code, and displayed in the Adobe Digital Editions reader.

The icons in the upper-left part of the window let you display a list of all the available ebooks, select a specific one, and pick various reading options, such as changing the text size, copying and pasting text, and adding bookmarks. Some of these options are also available as icons in the upper-right part, which list the page you're on and the total number of pages, or allow you to insert bookmarks, change the text size, and perform a search. All in all, it's a pretty straightforward interface.

The ePub support in RoboHelp 9 has two non-standard interface features that you may trip over the first time you generate ePub output.

• You're probably accustomed to double-clicking a desired output specification in the Single Source Layouts pod to display the "Generate… output" dialog box, defining your settings, generating, and clicking the View Output button to see the result. But this doesn't generate and display the ePub output. Instead, it displays an XML control file for the output. To display the ePub output in RoboHelp 8, you run the script from the Script Explorer pod, a habit which may have carried over to RoboHelp 9. But…
• Double-clicking the script on the Script Explorer pod does not run the script. Instead, it opens the script in the ExtendScript Toolkit. To run the script, click on it in the Script Explorer pod, then click the Run… icon on the pod toolbar. Better yet in 9, just select File > Generate > ePub Output, without having to open the Script Explorer pod. This displays the ePub settings dialog box, where you can generate and view the actual ePub output.

These are minor problems and you'll get over them quickly. But if you're an experienced RoboHelper and accustomed to double-clicking to generate and view your output, you'll waste a minute trying to figure out why you're getting odd results.

The meaning of the term best practices often depends on its context. Here, I'll define it to mean two things – using coding and development practices designed specifically for ePub output and using practices in the general RoboHelp project that will translate well to the ePub output.

For the first definition, see www.adobe.com/go/learn_rh_epub_best_practices_en. This document focuses on programmatic standards and has a lot of useful information. (As a side benefit, it's an ePub ebook itself. So before downloading it, download and set up the Adobe Digital Editions viewer, at /products/digitaleditions/. The best practices document will then open in the ADE viewer and give you an immediate example of an ebook.)

For the second definition, here are some suggestions ranging from general to specific:

• Set and adhere to standards. Syntax violations and shortcuts will come back to haunt you when you have to fix them by hand.
• Use styles and CSSs for all formatting, including character styles such as bolding. Many people use CSSs for paragraph styling, like head styles, but use the text formatting toolbar for character styles; this works if you're disciplined enough to only use the toolbar for character styles. But that's hard; the toolbar is right in front of your eyes and so convenient to use for other formatting too. The best solution is to define all styles, including character styles, in the CSS, hide the text formatting toolbar, and do all formatting from the CSS. Mechanically, it's easy. The hard part is changing how you work.
• Keep your CSSs simple to make them easy to understand and maintain, and document them for the benefit of the next developer.
• Review your CSSs periodically to eliminate duplicate or unused styles.
• Validate your CSSs periodically. There are many validators; a good one is the W3C's at http://jigsaw.w3.org/css-validator. Tools like this find and highlight syntax errors in your code. Some may be irrelevant, but you'll at least know what errors exist and can make educated decisions about changing your development practices.
• Consider shifting from absolute to relative size units for styles. For example, instead of using points to define text size, consider using units such as % or ems. This is useful for single-sourcing to devices with different-size screens, such as smartphones and desktops, because it puts the display control workload in the browser's hands. For example, rather than defining H1 as 14 points, you might make it 140%. This seemingly trivial change tells each browser on each output device to make H1 40% larger than the default normal style for that device, and leaves it to the browser on the device to figure out what it means.
• Identify external and internal standards that authors must follow, such as W3C code compliance, whether to use the Mark of the Web, indexing, wording, conditional build tagging, and so on. Train authors to use those standards and enforce their use.
• Support company strategy. If you like technical and design challenges, you'll enjoy the process of moving to ebooks. But as you do, be sure that move supports your company's strategic direction and be prepared to help shape that direction.

In addition to the sources mentioned earlier, here are two more useful ones:

• EPUB Straight To the Point, Elizabeth Castro, PeachPit Press, 2011 – A good, quick overview of ePub and a discussion about converting Word and InDesign files to ePub.
• http://www.wvanweelden.eu/robohelp/scripts/ebook – Willam van Weelden's blog post about ePub in RoboHelp 8 and 9, and a discussion about converting ePub ebooks to .mobi format for use on a Kindle.

If you're considering going mobile, you may be concerned about having to buy and learn new tools only to find that mobile doesn't work for you and you wasted the effort. The support for creating ebooks in RoboHelp has a strategic aspect – you can try mobile with no need to buy new and unfamiliar tools. You're simply using a tool that you already have and know. And if mobile isn't what you thought it would be, just delete the mobile output and go back to your regular work. It's a pretty safe way to experiment.