The Detail Department

You are here: Home / confluence / Creating Word Documents from Confluence

Creating Word Documents from Confluence

by

Expanding on from my One thing in One Place,  Once post on reusing Confluence content, the next step is to export that content from Confluence into Word and or PDF to produce printable manuals from your content. Yes, I know, I have that thought too, why would you need to print something when it’s on Confluence and readable on the screen and directly linkable to the content. Well, sometimes I just have to lose that battle and understand that people do in fact like to have a paper copy of documents to read. So the important thing here is to ensure that the Word document or PDF content comes directly from your Confluence content so that you minimise the versioning issues. If you do a major update to your Confluence content, it’s a relatively straightforward matter of exporting and releasing a new version of your Word or PDF document.

To export from Confluence to Word I use Scroll Office from K15t. I have tried the Scroll Wiki exporter to export directly to PDF but it was an early version and I had some issues with it, and I prefer to tweak the export in Word first before doing the PDF output so I will focus on Scroll Office here. (There is also the Confluence PDF Export option if you want to play around with customising it to work for you). Scroll Office is a great product. There are some tricks to getting it working well, and there is still a little bit of tweaking required in the final Word document, but overall it is great – have a look at the documentationto get started with using it. And I must say that the guys from k15t have been very helpful in getting a few bug fixes done whilst I’ve been setting up this export process.My Confluence instance is a help system for a software product. The pages in Confluence are structured in a particular way:

  • Each screen in the software has a page in Confluence (this helps if we want to add som screen level context specific links to the app at a later date).
  • The hierarchy of pages in Confluence is set up exactly the same way as the menu structure in the software, that way people can navigate to the page that describes the screen they need some help about.
  • Each page describes what the screen does and also has a Navigation section that tells the user how would they get to this screen in the software. This is useful if they have come to this page via the search or via a hyperlink.
  • Each page also has links to the next most relevant topic, or the next screen that the user would use if they were on that screen.
When preparing the Word manual for the software there are a few differences with the way the content needs to be structured. As the document is in a linear form, and most users will be seeing the manual in their training course, we don’t really need all the navigation instructions or the links to the next topic, as the next topic is right below it on the page. There may also be some text that is specifically in the manuals such as training exercises or introductory comments. So there is a little bit of tweaking required in Confluence to be able to produce the ideal Word export.The first thing to understand when using Scroll Office is how Scroll Office handles headings – that will help you work out the way that the content for export should be structured. Basically the heading levels that have been used in Confluence are ignored and it all works on a hierarchy. Page Names are Headings in Word, then the h1. to h3. etc become headings under that heading. Pages in the hierarchy under that page also become headings, so depending on your hierarchy of your pages in Confluence you could have a very nested heading structure in Word. This is not ideal. So the trick (for me) is to create new pages in Confluence that will be my pages to export. I then include the content from my regular Confleunce pages into these pages and set up these export pages to have a much flatter hierarchy and heading structure (eg by including multiple pages into the one).

As mentioned above, I also want to exclude some of the content from my main pages in the export, so this is where the wonderful {builder-show} macro comes into it’s own. In the Base Page (the page where the content is edited), I wrap different content sections in the builder-show macro to show only certain parts of the page in the Base Page or the Manual Page. In the Manual page I use the {import}Macro to import the contents from the Base Page. See the example content below.

Page Setup in Confluence

Page Setup in Confluence for Word Export

This way I have two pages of content but only one page that I need to maintain. The next step is to import two or more pages into my manual page, separated by headings. It does not matter that these manual pages are quite long, because I hide them from the main navigation menu – the users who come via the navigation only see the Base Page.

Another trick I use is the {scroll-pagetitle} macro. I want the headings on the Word document to be the same as the headings on my Confluence content, but as I’m creating new pages to export the content, I can’t have the same page names in Confluence. So I just add the word Manual to the end of my page name for my manual pages and then use the pagetitle macro to revert back to the same title on the Word export.

Word Tweaks

Of course the best export from Confluence only happens if the Word Template is set up well with good heading styles (down to about heading level 6), bullets, numbering, headers, footers, page numbers, title pages etc. Spend some time tweaking your Word Template along with your export pages in Confluence to get the best results. There are some tweaks I do in Word, for which I use Macros (these are for things that are specific to my Confluence instance so I won’t bore you with the details). It is great that Scroll Office allows the document template to be a macro enabled template, so the macros are already built into the document when the document is exported.I do suggest that you do a thorough check over your Word document once it has been exported and tweak the content looking out for the following:

  • Update the Table of Contents.
  • Remove additional paragraph returns after images (k15t said they plan to fix this in an upcoming release).
  • Adjust page breaks.
  • Check spelling again (yes, it is amazing how many spelling errors you pick up seeing it in a different format).
  • Resize images or adjust formatting if it helps to get things to fit on the pages better.

The less you need to do with final tweaking in Word the easier it is to re-export the content next time.

The final step is to save the Word document as a PDF file, which of course Word 2010 does out of the box. After you have created this PDF file it may even be worthwhile adding these documents to a page in your Confluence site so that users can download the completed PDF file.

Using these steps I have been able to create 3, 150 page word manuals and a few smaller quick guides on how to use the software – all based on the base content pages.

I hope this helps you, but if you have any tips or other suggestions on how to get great looking printed manuals from your Confluence content then please let me know in the comments.