Publishing documentation to ebooks from Confluence wiki
I’ve been having such fun over the last couple of days, playing with the Scroll Wiki EPUB Exporter. It is a plugin (add-on) for Confluence that converts wiki pages to EPUB format. What amazed me was how easy it is to create ebooks this way, and how very shiny they look on an iPad. A definite “ooh” moment.
The Scroll Wiki EPUB Exporter exports Confluence pages to an EPUB file. EPUB is an open ebook (electronic book) format developed and maintained by the International Digital Publishing Forum. EPUB supports reflowable content, meaning that the content’s layout changes to suit the device on which the content is being read. HTML is another example of a reflowable format. A growing number of devices support the EPUB format, including the iPhone, iPad, Android devices and a number of ebook readers and tablets.
I used the Scroll Wiki EPUB Exporter to convert the Bitbucket user’s guide from Confluence wiki to EPUB format. Then I pulled the EPUB file into the iBooks app on the iPad. Here’s what it looks like in iBooks:
I’m a technical writer, so now I’ll show you how to do it. 🙂
Installing the EPUB exporter plugin
First I installed the EPUB plugin onto my test Confluence site. In case you’d like to try it out too, here’s a quick guide to installing a plugin into Confluence. You need Confluence system administrator permissions to do this:
- Choose “Browse” > “Confluence Admin” > “Plugins” > “Install“.
- Type the name of the plugin (“Scroll Wiki EPUB Exporter”) into the search box and click “Search“.
- Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
- Click “Install Now“.
Alternatively, download the plugin (it’s a JAR file) from the Atlassian Plugin Exchange and save it on your computer. Then go to the Confluence plugin installation page, as described above, and click “Upload Plugin” to upload and install the plugin JAR file manually.
Next I emailed the team at K15t Software (firstname.lastname@example.org) asking for an evaluation licence. When it arrived, I installed the licence key onto my site. Here’s how:
- Choose “Browse” > “Confluence Admin“.
- Click “License” under “Scroll Wiki EPUB Exporter” at the bottom of the left-hand navigation panel.
- Paste the licence key into the text box.
- Click “Save“.
Ready to epublish!
Converting Confluence pages to EPUB
Once the Scroll Wiki EPUB Exporter is installed, there’s a new option in the Confluence “Tools” menu: “Export to EPUB“. Click it to see the export screen:
The plugin produces a zipped file with a .epub extension. Next, I wanted to see the document on an ebook reader of some sort. There’s an iPad in the house, so let’s try that.
To get the file onto my iPad, I emailed the file to myself (well, actually to Peter, because the iPad is his). I opened the email message on the iPad, tapped the attached file and tapped “Open in iBooks“.
And voila, it’s as easy as that. Here’s another picture of the Bitbucket documentation open in iBooks on the iPad:
iBooks is a built-in app (application) on Apple’s iPad 2. It is also available for download from the App Store.
Two things came to mind
While writing this post, two things struck me.
Firstly, I wanted to take a screencast so that I could post a video showing the page turning and other cool aspects of iBooks. There’s no way to make a screencast on the iPad! I would have had to make a video using a camera.
Secondly, I started thinking about the content itself. It’s great that we can now make ebooks so easily. Technically, the problem is solved. Write the content in Confluence then export it to EPUB and people can read it on all sorts of devices.
But we need to think about the actual content. People using ebooks will not necessarily want to click links that point to websites and the infamous “more information”. They may not even want a practical “how to” guide. In the case of the Bitbucket guide in particular, people on ebook readers probably will not be able to write any code or access their source repository to try out the steps. Instead, perhaps the content destined for an ebook should be more of an overview, introductory or inspirational nature.
Love the EPUB exporter plugin
The Scroll Wiki EPUB Exporter is in beta release at the moment. I’m sure the developers would love any feedback we want to give. Anyone can write a review on the plugin page. Congrats to the guys at K15t Software – consider my hat doffed!
Posted on 7 August 2011, in Confluence, open standards, technical writing, wiki and tagged Confluence, ebook, EPUB, epublishing, Scroll Wiki Exporter, single sourcing, technical documentation, technical writing, wiki. Bookmark the permalink. 19 Comments.