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:

Publishing documentation to ebooks from Confluence wiki

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:

  1. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install“.
  2. Type the name of the plugin (“Scroll Wiki EPUB Exporter”) into the search box and click “Search“.
  3. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  4. 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 (sales@k15t.com) asking for an evaluation licence. When it arrived, I installed the licence key onto my site. Here’s how:

  1. Choose “Browse” > “Confluence Admin“.
  2. Click “License” under “Scroll Wiki EPUB Exporter” at the bottom of the left-hand navigation panel.
  3. Paste the licence key into the text box.
  4. 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:

Publishing documentation to ebooks from Confluence wiki

Scroll Wiki EPUB Exporter options

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“.

Publishing documentation to ebooks from Confluence wiki

Opening an EPUB file from email on the iPad

And voila, it’s as easy as that. Here’s another picture of the Bitbucket documentation open in iBooks on the iPad:

Publishing documentation to ebooks from Confluence wiki

Bitbucket documentation 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!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 7 August 2011, in Confluence, open standards, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. 19 Comments.

  1. How do the books look on a Kindle?
    One of the biggest challenges with ebooks is getting the tables to look presentable – have you had a chance to investigate that aspect?

    • Hallo Ellis

      I’ll have a go at loading the file onto a Kindle and get back to you.๐Ÿ™‚

      As far as the tables are concerned: the Bitbucket documentation that I used has a few simple, two-column tables with header row. They work well.

      Here’s a screenshot from the iPad, with the text at the default size:

      And here’s another shot, with the text size increased so that the table flows over more than one page:

      Cheers
      Sarah

    • Hallo again Ellis

      The Kindle does not support the EPUB format directly. You need to convert it to a format that the Kindle supports. That seems to be a fairly easy process. I found some very useful information in this post:
      http://my-ebooks-reader.com/2011/05/what-is-epub-and-can-i-read-epub-on-kindle-three-ways-to-do-it-from-my-ebooks-reader/

      I converted my EPUB file to a MOBI file using this online service:
      http://ebook.online-convert.com/convert-to-mobi

      Then I uploaded it to the Kindle. It’s not perfect, but it was an interesting exercise. I think the Kindle is better suited to straight text rather than technical documentation. Here is a photo of one of the pages on the Kindle:

      Cheers, Sarah

      • You can also save them as .prc files and upload them to the Amazon book store that way. I’ve seen the extra lines appear with content converted from Word – it seems better to write in HTML. I seem to recall you can fix it by searching and replacing for the surplus p tags.

      • Hallo Ellis
        Or we can just use PDF. Confluence does a pretty good PDF export, and the Kindle supports PDF.๐Ÿ™‚
        Cheers
        Sarah

  2. iPad Screencasts – You can capture the iPad video via the HDMI output. See http://www.youtube.com/watch?v=Vho_GVXd5xs

    The problem I understand is that the iPad doesn’t allow for a screencasting app and another app to run at the same time.

  3. Even though I understand that everybody is mostly exited about Steveยดs i-Stuff – has anyone tried it on an Android device? Should not be to much difference, I think?

    • Hallo Axel

      It would be great to see the results on an Android device. Alas, I only have iThingies in the house! I tried uploading the EPUB file to WordPress but it won’t let me upload the .epub file type, “for security reasons”.

      Let me know if you would like me to email you the EPUB file. I can use the email address you gave when you posted your comment.

      If anyone else would like the EPUB file to experiment with, drop a comment here too. Your email address will not appear on the blog. The file is 1.319KB in size. I also have a smaller one of 40KB (just a single page.)

      Cheers, Sarah

      • Hi Sarah,
        that would be quiet interesting – I would be happy to test it on an android tablet (Archos 7′ tablet) and an android phone.
        As I mentioned, I donยดt think there should be much difference but I will let you know. (And make some screenshots if I manage to figure out how to take them๐Ÿ™‚ )

        Regards from germany,
        Axel

      • Hallo again Axel
        The EPUB file is on its way to you.๐Ÿ™‚
        Cheers. Sarah

      • I’m delighted to report that Axel tried out the EPUB file on his Samsung Galaxy S2 phone using the Aldiko eBook Reader, and it worked beautifully. Here are some screenshots that he sent me:

        Screenshot 1

        Screenshot 2

        Screenshot 3

        Screenshot 4

        Thank you so much, Axel.๐Ÿ™‚

  4. Interesting. O’Reilly is using DocBook from some authors (e.g., me) and then generating four or five formats for their e-book offerings. Sarah and I bounced around ideas about using Confluence for the editing and then exporting to DocBook from there. The final choice is that emacs is faster for DocBook for me.

  5. Sarah,

    Thanks for some great and informative posts along the way. Please could you shoot the EPUB file in my direction as well?

    Thanks,
    Jeppe

  6. Sarah, thanks for sharing your experience on EPUBs.
    I think K15t guys are doing an awesome job by coming up with really cool solutions for technical writers community using confluence for authoring and publishing content!!
    I had been a great fan of their Exporter plugins including EPUBs and the new SCROLL Versions software which makes confluence apt for tech writers!! Do check that out,

    Cheers,
    Pooja

    • Hallo Pooja
      What a great comment! I agree with you: The K15t guys are awesome. We’ve been working with them on the new Scroll Versions plugin. It’s going to revolutionise the way we use the wiki.๐Ÿ™‚
      Cheers, Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: