Blog Archives

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!

Content reuse on a wiki – a case study

Recently I finished developing the documentation for a new user directory management framework that’s incorporated into two of our products. When designing the documentation, one of the primary goals was efficient and effective content reuse. Since we do all our documentation on a wiki, this was an interesting and rewarding exercise. So I thought you may like to read about it. 🙂

The reusable chunks of documentation are in the User Management (USERMAN) space on our documentation wiki. The chunks are used in the Confluence administration guide and the JIRA administration guide.

What the documentation is about

The documentation describes a software framework for managing user directories. A user directory is a place where you store information about users and groups. Using the software, administrators can connect various types of user directory to their application, and manage the directory connections. A directory can be an internal directory, with data stored on the product database, or an external LDAP directory like Active Directory, or even another application that manages the user information and directory connections.

Why content reuse makes sense for this documentation

The user directory management framework itself consists of a set of back-end libraries and a user interface plugin. The libraries and UI plugin are currently used in two separate products, Confluence and JIRA. The business rules followed by the back-end process and the UI experience are therefore the same in both Confluence and JIRA. In future, other products may join the party.

It makes sense to share the documentation too. This will ensure a consistent experience for our customers across the products, and improve our efficiency when maintaining the documentation.

Introducing the USERMAN space

The User Management (USERMAN) space contains the reusable chunks of documentation. Its home page looks a little different from our standard documentation home pages. A standard home page introduces readers to the documentation and gives them links to the user’s guide, administrator’s guide, and so on.

Instead, the USERMAN home page:

  • Lets readers know that “This documentation is not intended to be read independently of the JIRA and Confluence documentation” and gives them links to those documentation spaces. This is necessary because many people come to our documentation via Google searches. If they land on this home page, we want them to find their way to the relevant documentation quickly.
  • Tells authors where they can find the reusable chunks within the space.
Content reuse on a wiki - a case study

Home page of the USERMAN space

A simple example of content reuse

Let’s start with a simple topic, configuring the LDAP connection pool. The reusable chunk is in the USERMAN space: _LDAP Connection Pool Settings. Here’s a screenshot of the content of that page:

Content reuse on a wiki - a case study

A chunk of reusable content

The above page consists entirely of reference information. There is no orientation at the top, nor any other context apart from the standard message telling readers where to go for the “real” documentation.

The content of the page is reused in both the JIRA documentation (Configuring the LDAP Connection Pool) and the Confluence documentation (Configuring the LDAP Connection Pool). Here’s what it looks like on the JIRA page:

Content reuse on a wiki - a case study

LDAP connection pool in the JIRA documentation

On the JIRA page shown above, there’s:

  • Contextual information at the top of the page.
  • JIRA-specific “how to” instructions.
  • Reused content: The chunk of reference information, dynamically copied in from the USERMAN space when the page loads into the browser.
  • More contextual information, in the form of “related topics”, at the bottom of the page. (Not shown on the screenshot.)

How do you include content from one page into another?

Confluence wiki provides the {include} macro. To use the macro, you edit your page and enter the macro name in curly brackets, specifying the space key and the page title of the page that you want to include into your page.

For example, the above JIRA page contains this macro code:

{include:USERMAN:_LDAP Connection Pool Settings}

When Confluence renders the page, it will replace the macro code with the content of the “_LDAP Connection Pool Settings” page from the “USERMAN” space.

If you like, you can find out more in the documentation for the {include} macro.

The design of the reusable content

Here’s a summary of various design considerations and decisions:

  • Reusable content in a separate space. I decided to house the reusable chunks in their own space, rather than in one of the product documentation spaces. This is because the information is independent of any specific product.
  • Reusable chunks hidden from the reader. Well, as much as possible. The topics in the USERMAN space are not visible in left-hand navigation bar, but people will find them if they search for them. We need to make it clear to readers that the USERMAN space is not intended for reading independently of the product documentation. We also give readers links pointing to the relevant JIRA and Confluence documentation.
  • Inclusions library. Put the topics in an “inclusions library” and start each page name with an underscore. This will alert both readers and authors to the fact that there’s something different about the page, and will help prevent people from changing the page name (which breaks the auto-inclusion). A while ago, I wrote a post about inclusions libraries. One thing to note is that an “inclusions library” is not a feature of the wiki. It’s just a convention we have adopted. The page called “_InclusionsLibrary” is just a page with a funny name. 🙂
  • Spaces as a mechanism for version control. When we release a significant new version of the user management framework (either the back-end libraries or the front-end user interface) we will need to publish a new version of the documentation too. Then, as each product incorporates the new version of the user management framework, we will adjust the product documentation to include the relevant version of the user management documentation. To make this work, we will create a new USERMANxxx space for each version of the documentation. The “xxx” represents the version number.
  • Size of the reusable chunks. How do we decide how big the reusable chunks should be? Well, this is a biggie, so I decided to devote a whole section to it. See the next section, after the screenshot.

Looking at a tree view of the pages in the USERMAN space, you’ll notice that the space home page (marked with the house icon, and at bottom of the screenshot) has no child pages. In a “normal” documentation space, you’d expect most of the pages to be children of the home page. Instead, in USERMAN all the pages are children of the “_InclusionsLibrary” page.

Content reuse on a wiki - a case study

Tree view showing the pages in the USERMAN space

Deciding the size of the reusable chunks

On the one hand, the smaller the chunks the better. Small pieces of content give us much more flexibility. We can use them in different sequential orders and in different contexts. We can add product-specific and contextual information between the chunks. We can leave out bits in one product and include them in another. We are less affected by changes in the user interface, for example when the order of the input fields changes or entire sections move to different screens.

On the other hand, smaller chunks are more difficult to manage. Every time we need to update the page inclusions, such as when we need to move to a new version, there are a large number of {include} macros to update. This reduces the benefit of efficient maintenance. Too much flexibility may lead to confusion in the final output that the reader sees, reducing the benefit of cross-product consistency.

You could go to one extreme and have a reusable chunk per input field or concept (“setting the optimal size for your LDAP connection pool”). Or you could go to the other extreme and define one large reusable chunk per user task (“connecting an LDAP directory”).

After discussion with the product manager and development team, I decided to go for a middle-of-the-road approach.

  • Most of the reusable content is reference material and conceptual material, rather than “how to” steps.
  • We divided the content into logical blocks, corresponding to a logically-related set of input fields or to a concept.

The result is:

  • For the simpler task-based topics, there are two page inclusions: one for the concept and one for the reference material. Example. (To see the wiki markup source of a page, click “Tools” and select “View Wiki Markup” from the dropdown menu.)
  • For the more complex topics, the number of inclusions ranges from five to ten: one or two conceptual chunks,  a number of reference chunks and one or two illustrative chunks. Example 1. Example 2.

What about the procedures and context that are specific to the product?

In the documentation pages for Confluence and JIRA, there are sections that are specific to the product and sections that are common to both products.

These bits are specific to the product, and therefore not reusable:

  • Procedures: The primary user interface is different for each product, and so the path that the user takes (click here, select this, click that) to get to the directory connection screens is specific to the product. Once the user has reached the directory connection screens, the user interface is the same for both products.
  • Context: It’s a good idea to start each page with a mention of the product (Confluence or JIRA) and other orienting information, so that the reader knows what the page is about. After that, it’s safe to dive into the reused content which, of course, is free of contextual information.
  • More context: The path within the documentation itself differs. For example, we need to give people links to related topics and parent pages.

Each documentation page therefore has a section or sections of reused content, with a wrapping of product-specific content.

Diving into a more complex example of content reuse

Let’s take a look at a complex topic, connecting to an LDAP directory.

The topic has a number of sections:

  • A short introduction to the page.
  • An overview of the LDAP connections provided and why you’d use them.
  • A “how to” procedure.
  • Seven sections containing details of specific settings.
  • Diagrams of possible configurations.
  • Related topics

Only three of the above sections contain content specific to the product:

  • The short introduction.
  • The “how to” procedure.
  • The related topics.

All the other sections are drawn from reusable chunks:

  • An overview of the LDAP connections provided and why you’d use them.
  • Seven sections containing details of specific settings.
  • Diagrams of possible configurations.

To see this at work, go to the page (for example, in the Confluence documentation, Connecting to an LDAP Directory), hover over the “Tools” button and select “View Wiki Markup” from the dropdown menu. You’ll see that most of the page consists of headings and {include} macros like this:

h2. Server Settings
{include:USERMAN:_LDAP Server Settings}
h2. Schema Settings
{include:USERMAN:_LDAP Schema Settings}
h2. Permission Settings
{include:USERMAN:_LDAP Permission Settings}

The first {include} macro draws in a reusable chunk from this page in the USERMAN space: _LDAP Server Settings.

The corresponding page in the JIRA documentation (Connecting to an LDAP Directory) looks very similar to the Confluence page.

Reusing Gliffy diagrams

This is something pretty cool that I discovered when creating this set of documentation. You can use the {include} macro to pull in a page that contains a Gliffy diagram. Let’s say you have a Gliffy macro on Page A. Then on Page B, you insert an {include} macro that pulls in Page A. Confluence will faithfully reproduce the diagram on Page B, as well as Page A.

That’s awesome!

Here’s an example. This page in the USERMAN space contains just a Gliffy diagram and its caption: _Diagram Confluence JIRA Crowd.

Here’s a screenshot of the above page:

Content reuse on a wiki - a case study

A reusable Gliffy diagram

Reusing the diagram:

Developing the design

The exercise of designing the reusable content was interesting in a couple of aspects.

  • First, the end result would be a set of reusable chunks, only loosely resembling the “documentation” that most subject matter experts are used to seeing. How could I prototype the design and the content with them?
  • Secondly, the content would be used in two different sets of documentation, for two different products: Confluence and JIRA. Only the Confluence documentation is “mine”, in terms of technical writing responsibilities. Two other technical writers manage the JIRA documentation. I needed to make sure they had input into the design and were happy with the end result.

The usual process of consulting and collaborating with subject matter experts when designing a new documentation suite goes something like this: Draft the table of contents, review it with product managers and developers, apply changes, add detail, and refine it until we’re all happy.

The difference was that there were two tables of contents:

  • The list of topics and their hierarchical structure as they would appear to readers. Let’s call this the compiled documentation
  • The list of reusable chunks that we would plug together to form the above readable material. Let’s call these the reusable chunks.

My strategy was to discuss and review the planned table of contents for the compiled documentation in great detail, making sure that I covered all topics and was consistent in the amount of attention given to each subject. Then I designed the reusable chunks to best satisfy the requirements so discovered. When designing the reusable chunks, I relied more on my technical writing and information design skills.

As soon as we had a basic design, I created the draft content in the reusable chunks and hooked them together to create the compiled documentation for one of the products.

Then I walked the technical writing team, product managers and developers through that first draft. I showed them the reusable chunks and discussed the design strategy (size of the chunks, use of wiki spaces, setting of permissions, consistency, removal of context, and so on). But most of our attention focused on the human-readable documentation. The review session, as always, gave me much valuable feedback that I applied to the draft.

After that initial review, I focused on each individual topic and went through the usual iterative procedure of drafting, reviewing and updating the content.

The tools

A summary of the tools I’m using for this case study:

  • Confluence wiki.
  • The {include} macro, supplied as part of Confluence.
  • Spaces, the primary way of organising content into logical collections, or libraries, in Confluence.
  • The Documentation theme, supplied as part of Confluence. In fact, you do not need the Documentation theme for content reuse. All of the techniques mentioned in this post will work in the default Confluence theme and most other themes too. But I’ve mentioned the Documentation theme here because the screenshots show it in action, in particular the left-hand table of contents supplied by the theme.
  • Gliffy online diagramming tool. Again, this tool is not needed for content reuse. I’m including it in the list because it’s an interesting part of the case study.

That’s it for now

I hope you find the examples and design tips useful!

More about content re-use on a wiki

A while ago I wrote a post about content re-use on a wiki. Just recently I’ve discovered that the {excerpt} macro has a handy parameter: “hidden=true”. So I thought I’d tell you about it.

In  Confluence wiki, you can dynamically include content from one page into another page. These are the macros to use:

  • Use the {include} macro to include a whole page into another page.
  • Use the {excerpt} macro to define a re-usable chunk of text (an ‘excerpt’) that is part of a page, then include that excerpted text into another page using the {excerpt-include} macro.

My recent “eureka” moment happened when I noticed the “hidden” parameter in the {excerpt} macro:

{excerpt:hidden=true}Blah blah blah.{excerpt}

If you specify “hidden=true”, the content between the {excerpt} tags will not be displayed on the page where the excerpt is defined. It will, however, be displayed on the page where the excerpt is used via the {excerpt-include} macro. Magic!

Here’s an example of a page that does just that. It’s from our SharePoint Connector documentation: _Access Confluence using IWA with IIS

I’ve added some text to the page, explaining that the content is hidden and telling people how they can see it if they really want to. Here’s a screenshot of the same page (click the image to expand it):

More about content re-use on a wiki

More about content re-use on a wiki

Why on earth would you want to hide the content of an excerpt?

It stems from the way we are using content re-use in our structured technical documentation. My earlier post goes into it in detail. Here’s a quick summary.

We create a special “area” of the wiki, which we call the “inclusions library”. It’s not really anything special. It’s just a set of pages that hold the chunks of content (text, images, etc) that we will use more than once, on various wiki pages. We also use an underscore at the start of the page names, to remind us that the pages are special. This helps to prevent us and other authors from editing the included content by mistake.

The thing about a wiki, though, is that people may stumble across the pages in our “inclusions library”. They may wander in via Google search, and not realise that this page is just part of a set of instructions. Sure, it’s got a weird page name. But hey, it’s a wiki. What do you expect?

It may even be a bit traumatic for them if they start following the instructions, without having performed the preceding steps. 😉

Here’s one of the pages that use the excerpt from the above page. This page is neatly in place in the full installation sequence: Access Confluence using Integrated Windows Authentication via IIS with SP 2010. Much less chance of our poor Googler going off the beaten track.

I think the “hidden=true” parameter is pretty neat. I don’t know why I didn’t notice it before. Now you know about it too!

WebWorks ePublisher for converting documents to Confluence wiki

Over the past couple of weeks I’ve had the chance to experiment with WebWorks ePublisher, a set of tools that converts documents from Word, FrameMaker and DITA XML to a number of different output formats. One of those output formats is Confluence wiki. It’s been very interesting, so I thought I’d blog about it and see if anyone else wants to give it a go as well.

I started off knowing a bit about what ePublisher can do, having attended a WebEx demo. But I had never used it. This was such fun! Most of this blog post is going to look like a “how to” guide, because I’m hoping it will be useful to people who want to try this tool too.

A quick introduction to ePublisher

ePublisher is not a Confluence plugin. It is a set of standalone tools that can publish to Confluence as one of the output destinations. ePublisher allows you to transform content from Word, FrameMaker or PDF into a number of different output formats, including Confluence. It also provides a number of styling and design options for you to tailor the output documents.

These are the three components of ePublisher:

  • ePublisher Pro – Use this component to design your “stationery” i.e. the appearance of the documents that ePublisher will output.
  • ePublisher Express – Use this component to generate your documentation.
  • ePublisher AutoMap – Use this component to automate the documentation generation process, and to perform batch processing, scheduling, etc.

The Evaluator Guide is in the form of a video tutorial.

Requirements

Because I wanted to convert my documents to Confluence wiki, here’s what I needed:

  • Confluence version 2.10.2 or later. I’m using Confluence 3.0.
  • Confluence remote API and XML RPC API enabled.
  • The Content Formatting Macros plugin for Confluence, created and maintained by Adaptavist. This is a free plugin. You can install it directly from the Confluence administration console. (Instructions below.) The plugin is not officially supported by Atlassian, but is supported by Adaptavist.
  • If your input documents are in Word or FrameMaker format, then you will need Word or FrameMaker installed on your machine. Supported formats are:
    • Microsoft Word 2000 to Microsoft Word 2007.
    • Adobe FrameMaker 6.0 to Adobe FrameMaker 8.0. I don’t have FrameMaker, so I didn’t try this out.
    • DITA XML 1.0 and 1.1.
    • In addition, for DITA input documents you will need the Java Development Kit (JDK) 1.4.2 or later. I have Sun JDK 1.6. You need this for Confluence too, so if you’ve already got Confluence you’re cool.

Install ePublisher and Confluence

Download WebWorks ePublisher and install it. I was using a full version of ePublisher, complete with all three components. If you’re looking for a trial version, you can try out the ePublisher Express part of the product for free.

Download Confluence and install it. You can get a free 30-day trial licence or a free personal licence.

Set up additional requirements in Confluence

1) Install the Content Formatting Macros plugin into Confluence. Step by step: Open the Confluence ‘Browse’ menu and select ‘Confluence Admin’. Click ‘Plugin Repository’ in the left-hand panel. Find the ‘Content Formatting Macros’ and click ‘Install’. Wait a while for the process to complete. It will eventually say “Installed” in the table next to the macro name.

2) Enable the remote API in Confluence. Step by step: Click ‘General Configuration’ in the left-hand panel of the Administration console. Click ‘Edit’ and click the ‘ON’ radio button next to ‘Remote API (XML-RPC & SOAP)’. Save the change.

3) Create the Confluence space where you want to put your documents. I gave my space a key of ‘TESTEPUB’. Note that you must create the space in Confluence before you deploy content to it via ePublisher.

Here’s my space:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

Use ePublisher Pro to design the styles and format for your output documents

You will start off with a template created in the original software for your input document(s). For example, if your input documents are in Word, then you will import your Word template into ePublisher. If you also have input documents in FrameMaker then you will need a FrameMaker template to import into ePublisher.

Hint: For a quick start, if you don’t have a Word template you can just use the Word document you want to convert as your template. That’s what I did.

You will import your template(s) and/or sample document(s) into ePublisher Pro. ePublisher Pro will analyse the styles in the imported documents and provide you with a list of styles. You will then map the styles to your requirements for your output documents.

1. Open ePublisher Pro and create a new project. When you create the project, you will also define the output target. Because I wanted to create Confluence wiki pages, I selected “Wiki – Confluence” as my target. (You can add other targets later too, via the “Manage Targets” menu option.)

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

2. Add your templates or sample documents to the new project. You can do this as part of the create-project procedure. Or you can do it afterwards, by clicking ‘Project’, ‘Add Document’.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

3. ePublisher Pro will scan your documents and extract all the styles, putting them into your new project.

4. Now you can map the styles from the input documents to the styles you want for your output documents. In ePublisher Pro, click the ‘Style Designer’ icon in the top tool bar. (When you move your mouse over the tool bar icons, a prompt appears in the status bar at the bottom to tell you what the icons mean.)

5. You will see a list of the styles extracted from your input documents, categorised into groups like paragraph styles, character styles, table styles etc. You can also add new styles, by clicking the ‘New Style’ icon (a tick mark) in the styles toolbar.

For each style, there are two tabs: the ‘Properties’ tab and the ‘Options’ tab. This is where you can determine your output styles, and also things like page breaks via ‘Page Break Priority’ (e.g. start a new page for each heading level 1) and table of contents levels.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

6. Save your style definitions by choosing ‘File’, ‘Save as Stationery’.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

That’s the ePublisher Pro part of the process done, i.e. the design work that will often be done by specialised designers. Now you can put on your document publisher hat and start converting your documents.

Use ePublisher Express to convert your input documents to the chosen output format(s)

1) Start ePublisher Express.

2) Create a new Express project. When it prompts you for stationery, select the stationery that you created from your input document templates earlier.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

3) Add your input documents. You can do this while creating the project, or later via ‘Project’, ‘Add Document’. I did it by dragging the documents from my Windows file explorer into the ePublisher Express window.

Hint: When dragging and dropping, you need to drop the documents directly into the folder in the Express ‘Document Manager’ panel, not just into the panel itself.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

I added a number of Word documents, and also a DITA document just for fun. I used the DITA sample document from project Gutenbert: 20,000 Leagues Under the Sea by Jules Verne. I simply dragged the ‘ditamap’ file into my ePublisher Express project. Here’s the result:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

4) Next I needed to tell ePublisher Express what output format I wanted. I did this by adding a ‘Deployment Target’. Step by step: Click the ‘Target Settings’ icon in the ePublisher Express toolbar, then click ‘Add deploy target’, then ‘Add’. Select ‘Wiki – Confluence’ then ‘Edit Configuration’. A popup dialogue now asks you for the location of your Confluence site and the space key. This is the wiki space where your documents will end up. I entered the URL of my Confluence wiki (http://localhost:8080) and my space key (TESTEPUB):

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

After adding the new deployment target, I selected the Confluence target in the ‘Deploy to’ field as well:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

5) Now for the fun part! 🙂 I clicked the ‘Generate All’ icon in the ePublisher Express toolbar. Sure enough, the generation process started:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

6) Antici… pation!Excitement! I kept flipping between my ePublisher window and my Confluence screen, to see the wiki pages appear.

Duh! This is where Sarah calls herself a “banana”.

ePublisher for converting documents to Confluence

I hadn’t realised that there’s another step required if you are publishing your content to a wiki. The generation process produces the output files, containing wiki markup, CSS and your text. Then you need to deploy the content to the wiki. I tried various configurations, then gave up and called WebWorks for support. That support WebEx session must be the shortest in history. 🙂

7) Deploy your content to the target — In ePublisher Express, click ‘Target’ then ‘Deploy’:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

8) Yippee! My pages appeared in Confluence. If you leave all the design settings at their defaults, as I did, then you get a table of contents page and some neat navigation buttons at the top of every page. Here’s the automatically-generated table of contents page:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

For my quick and dirty experiment, I exported some of the Crowd documentation pages from Confluence to Word, then pushed them through ePublisher to put them back into Confluence. Here’s one of the resulting pages back in Confluence:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

And here’s a page from the Jules Verne DITA document, in the same Confluence space:

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

What happens when you update or comment on wiki pages?

After deploying my pages to Confluence, I updated a page in Confluence and also added a comment to the page. Then I redeployed the content from ePublisher.

When you deploy your content from ePublisher, it updates any existing pages with the content from the ePublisher source document. In effect, if you have updated the page in Confluence, your change will be overwritten by the ePublisher deployment. The page history retains every version of the page. The comments on the wiki page remain untouched. (This is as you would expect, because ePublisher uses the Confluence API to apply the updates.)

There is no “round trip” option available, i.e. you can’t update the pages in the wiki and then export the updates back to your source documents via ePublisher. The tool is intended for people who use Word, FrameMaker or DITA as their primary authoring environment, or people who want to convert their documents to wiki format permanently.

Conclusion

This was a rough-and-ready test, because I didn’t have time to set up my own templates or design stationery to make my output pretty. Even so, it was easy to push my Word and DITA documents through to Confluence and to produce a wiki documentation set that has a consistent format and navigation. Apart from my “banana” moment, the process was quick and painless.

I’d like to spend more time exploring the setup of the templates and of the stationery, to see how I can refine the output and tailor the Confluence pages to a specific style. Just examining the options available in ePublisher shows that it has a lot to offer in this respect. Alas, I don’t have time right now, and I wanted to blog about how far I’ve got without waiting til I do have time.

I’d also like to explore ePublisher AutoMap, which lets you automate the generation and deployment processes. This means that you can schedule batch jobs to tackle large volumes of documentation and to do the conversion on a regular basis.

I hope the above step-by-step guide through my experiment will be useful to anyone who wants to try ePublisher with Confluence. This tool will be very useful to people who have a large set of legacy documents that they want to convert to wiki format, or people who want to author their content outside the wiki on an ongoing basis, and convert it regularly to wiki as well as other formats. Single-sourcing of content is great for environments where different readers or customers need their documentation in different formats.

More information

WebWorks are holding a Round Up ’09 conference in Austin on 19-21 October. There’s sure to be lots of information there, about using and publishing to wikis, social documentation and other interesting stuff. Wish I could be there too!

Bill Arconati wrote a post on the Atlassian blog, describing the demo the WebWorks guys gave us, including a video of the session.

Let me know if you decide to give it a go, and whether the step-by-step guide above was useful. If you get further into the templates, stationery and AutoMap side of things before I do, I’d love to hear your experiences too.

ePublisher Pro – Use this component to design your “stationery” i.e. the appearance of the documents that ePublisher will output.

ePublisher Express – Use this component to generate your documentation.

ePublisher AutoMap – Use this component to automate the documentation generation process, and to perform batch processing, scheduling, etc.

I found the online help shipped with the product more useful than the online documentation. Start ePublisher Pro and click ‘Help” to open the local help system in your browser.

AODC day 2 – Single source publishing

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference.

Here are some notes I took from the session on single source publishing, by Gareth Oakes from global publishing solutions (GPSL). GPSL is a major provider of PTC/Arbortext solutions. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

Single Source Publishing

This presentation was originally titled “Managing Modular Documentation”.  Gareth started with an orientation about the history of publishing, since the days when we were writing on cave walls. Then he discussed the benefits arising from single source publishing, and compared the workflows of traditional publishing versus single source publishing. He illustrated the difference between representational and semantic markup. DITA gives you the framework to start describing the semantic elements of a document.

Gareth’s thesis is:

“The single source approach is now recognised as global best practice.”

He discussed the components of a single source publishing system:

  • Authoring — Structured text; photographs and illustrations.
  • Publishing — To PDF, help files, web, mobile platforms.
  • Content management — Check out/in; version control and the ability to create/store a snapshot; workflow including review/approval; auditing and reporting.

Going into the authoring component in more detail

Unstructured content, such as a Word document, is not suitable for single source documentation. If you’re stuck with unstructured content, you’re not going to see all the benefits of single sourcing. Gareth says that XML is the best environment. It has a solid architecture and a wide support base. DocBook, DITA, S1000D and SCORM are some of the XML standards available.

So an important part of setting up your publishing system would be to design the data model and choose the appropriate XML flavour.

You also need to choose the right authoring tool. Gareth pointed out that some tools are better for different business environments e.g. when your data is highly structured and factual (needs good support for tables) rather than narrative or descriptive. You may need a tool that works well with images, or with mathematical equations. And the tool must work well with your content management system or other technical environment needs.

Talking about the publishing component in more detail

The publishing tool also needs to integrate well with your content management system. It needs to produce the output formats you require (PDF, help, web, etc). Also there may be specific output formatting needed, such as footnotes, rotated text. You may need automatic generation of table of contents, index, etc. Consider the performance side of things, especially if you’re producing large books.

Styling is usually part of the publishing process. You need stylesheets to determine the look and feel of your output. You need a tool that will make it easy to produce the stylesheets that suit your requirements.

Now the content management component (CMS) in more detail

Some people use just a network folder. But a database CMS has more advantages. You need to choose one that suits your business needs and environment, and you must consider whether it’s easy/difficult to set up. It’s better to avoid too much customisation and configuration, because this requires maintenance too.

Gareth listed the basic features of a CMS:

  • Check in/out
  • Version control
  • Searching and metadata — Can you add your own custom metadata, so that the search can recognise them too.
  • Access control — You need to control what people can do in your system.
  • Workflow
  • Reporting and auditing — Useful statistics about the publishing process.

Advanced features a CMS may provide:

  • XML support — Only 20% of CMSes support XML natively, particularly compound documents e.g. a book has a number of sections, stored separately. And this is a basic requirement for single sourcing!
  • Collaboration — Such as an approval process.
  • Publishing services — Gareth likes a CMS where the publishing service sits behind the CMS and you can drive it via simple workflow.
  • Auditing and reporting — Many CMSes do basic reporting, but some offer more complex and/or detailed reports.
  • Translation management — Managing interactions with the translation service provider. Some tools do this really well.
  • Web-based editing tools — Rather than needing a desktop client, the authors can log in to a web site and edit the content that way. Similar to a wiki.
  • Digital asset management — for images and illustrations.
  • Support for storing CAD models
  • Integration between the CMS and the authoring/publishing tools.

Question from the floor: How do you manage links from one topic to another, given that the topics are all held individually and are not visible to each other until published?

Gareth’s answer: Yes, that should be one of the advanced features too i.e. an index of available links and link management — referential integrity.

Looking at release management: You need to be able to make and store snapshots. Then you need to reference objects by release, either the latest one or a specific one. You also need to link the final output (PDF etc) with its source version.

There’s also the question of content branching i.e. when you create a new product, you often need to re-use existing material from the previous version. Do you copy the content or just reference the existing content? You’ll make this decision depending on the circumstances at the time.

Thank you Gareth for a thorough and detailed presentation.

%d bloggers like this: