A great thing about the Atlassian Community: we are not alone in our struggles.
I'd developed some "personal coping mechanisms" for using the Import Word Document feature in Confluence. When I joined the Atlassian Community, I learned that others had the same struggles, some on a much larger scale. So I'm sharing my personal "import survival guide," which has helped me move through the "denial" and "anger" stages of import to the more useful "bargaining" stage, even if I never make it all the way to full "acceptance."
I don't have all the answers here. My way of "getting closure" is to concede that text-heavy content with simple images and formatting is the best match to the import tool's modest capabilities. Until something changes, having realistic expectations of the tool and taking some steps to prep documents increases my chances of getting a significant head start on building new pages. (It lowers my blood pressure too.)
I hadn't encountered any issues with importing Word documents until I helped a developer import a particularly stubborn one. My eyes were opened: Word import is both convenient AND confusing. I had to weigh the benefits of instant import against the need to clean up the new pages. Was it worth it? I investigated.
I experienced the same confusion and frustration as other users, though on a smaller scale. My opinion: we've been spoiled by Word's very robust formatting capabilities and our expectations are high. However, the importer's capabilities are very modest (and sometimes buggy). That's not a good combination! Since "lowering my expectations" isn't a solution, I investigated to see what I could actually do something about.
In the "bargaining" stage of Word import, I discovered what risk factors existed and how I could mitigate them. This is the bulk of my survival guide.
Images get some extra attention, since images larger than 900 x 1200 pixels will stop the import process. Screenshots created on large monitors can easily exceed this limit. As suggested by the error message, one option might be to raise the size limit on imported images.
In addition, images may be resized by the import process; I personally think that converted images appear less crisp and sharp after import. I very often save images to disk and add them to the page afterwards.
Some MS Word features won't import, while others may return unexpected results. Your mileage may vary based on Confluence and/or Word versions. If I find these elements while scanning I bookmark them with CHECK_THIS or FIX_THIS, then I check them after import.
If the Word document contains characters special to Confluence wiki markup such as - (dash), * (asterisk), _ (underscore), | (pipe), or ! (exclamation point), etc. especially if found at the beginning of a line, they may be converted to their wiki markup value, or wrapped in a wiki markup macro to preserve the formatting. Pipe characters in particular can create strange-looking tables with cells and columns all over the place!
Here's what happened to a code comment box made with pipe characters after import:
When I added an apostrophe at the beginning of each line, I got this instead, which I can work with.
My investigations revealed that identical heading text plus specific import options could lead to overwriting existing pages without any warning! Yikes! So I take the following precautions.
That's a lot of preventative measures, review and fixing. It doesn't scale. I'm sorry.
If I had a lot of Word documents to process, I would consider Confluence add-ons that can bulk import MS Word documents, such as the All-in-one File Importer for Confluence or the Import/Export Utility for Confluence. Or I would look for a converter, browser extension or MS Word plugin to convert the document type. If I find an answer to that dilemma, I'll share.
Some documents do import smoothly. On those days, I feel blessed.
Other times, I end up creating, copying and pasting content one page at a time. Advantages: new pages where I want them; formatting preserved better; I can strip formatting altogether and start over; I'm warned if a page title conflicts; and touching the source document provides a review opportunity. This is often the method I recommend, unless the plan is to rely on Confluence's collaborative authoring to share and refresh the document.
Fortunately, I don't import many Word documents, and the ones I do don't give me too much grief. At least I can now more realistically assess the amount of effort it will take, and can better calculate the return on investment of using the tool. Its limitations are a barrier to sharing via Confluence, so I very much look forward to future improvements.
If readers have other tips for ensuring Word import success, I'd love to include them in the survival guide!
Calling all collaborators! Appy Hours on the Atlassian Community is a monthly event where 4 Partner and app vendor presenters go head-to-head with 5-minute demos for the title of Best App Demo. I...