Question: How do I add my DITA content in Confluence for SME review?

by Tom Johnson on Jan 9, 2015
categories: technical-writing

Someone recently asked me:

I am using DITA with structured Frame and Tech Comm Suite. Do you know the best output to use so the docs can be displayed in Confluence? The SMEs want to proofread in Confluence and use it for a knowledge base. Ideally, I'd like to output from DITA or Robohelp and then just upload to Confluence.

Great question! Mixing DITA and Confluence is a major challenge. I noted in my API doc survey that about a third of people working in the API doc space are using Confluence in some way. This poses a challenge if you're using DITA.

However, I recommend not porting the DITA content into Confluence. People may think they want to review content in Confluence because they're reviewing other content here and are familiar with the platform. However, if your content is in DITA, there's no easy way to get it in and out of Confluence without copying and pasting (as far as I know).

I'm not that familiar with the reviewing capabilities built into Adobe TCS. I use the Webhelp with Feedback option in OxygenXML (I have some detailed notes on it here). In the past, I've also imported imported my DITA content into a WordPress site to allow people to add comments.

Whatever method you use for SME review, try to find a method that allows these capabilities:

• The ability to iterate on the content during review (based on incoming feedback) so you can update topics before other reviewers begin their review.
• The ability for reviewers to interface with each other via comments.
  Historical comments so other reviewers can see the evolution of the content.
• The ability to present the content in the same form that users will view it in (rather than a rendered PDF or Word document).
• The ability for reviewers to review the content asynchronously on their own schedules and times.
• The ability for reviewers to see the updates you've already made to the content so they know their recommendations don't fall on deaf ears.
• The ability for reviewers to continue their review post-release since people are usually busy up until release time.

I elaborated with more detail here: Reviewing draft DITA content with subject matter experts: 6 essential points. Based on these considerations, I decided to use the Webhelp with Feedback option with Oxygen, but I'm also using Oxygen, so it fits well into my toolset and workflow.

How would you answer this person's question? What recommendations or best practice advice can you offer?