How to Migrate from Word to DITA

The need for migrating Microsoft Office^® Word documents to XML formats, and particularly to DITA, is quite a frequently encountered situation. As usual, migration from proprietary formats to XML is never perfect and manual changes need to be made to the converted content. However, the methods below should help you find the best approach for your particular case:

 Method 1

1. Open the Word document in MS Office, select all the content, and copy it.
2. Open Oxygen and create a new DITA topic in the Author visual editing mode. 
3. Paste the selected content. Oxygen's smart paste functionality will attempt to convert the content to DITA.

Method 2

1. Save your MS Office Word document as HTML.
2. Once you obtain that HTML, you have two possibilities:
   
   • In Oxygen, Select File->Import->HTML File to import the HTML as XHTML. Then open the XHTML in Oxygen and in the "Transformation Scenarios" view there should be four pre-configured transformation scenarios to convert XHTML to DITA topics, tasks, references, or concepts.
   • Open the HTML file in any Web browser, select all of its content, and copy it. Then open Oxygen, create a new DITA topic in the Author visual editing mode, and paste the selected content. Oxygen's smart paste functionality will attempt to convert the HTML to DITA.

Method 3

1. Open the Word document in the free Libre Office application and save it as DocBook. 
2. Open the DocBook document in Oxygen.
3. Run the predefined transformation scenario called DocBook to DITA.

Method 4

1. If the Word document is in the new DOCX format you can open it in Oxygen's Archive Browser view and then open the document.xml file contained in the archive.
2. Run the predefined transformation scenario called DOCX DITA. This ANT scenario runs the following build file: OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/net.sourceforge.dita4publishers.word2dita/build-word2dita.xml over the DOCX archive and should produce a DITA project that contains a DITA map and multiple topics. 
3. You may need to do some reconfiguring to map DOCX styles to DITA content. 

Note: This method may also be helpful if you want to run it automatically with scripts, since it is based on the DITA OT and DITA For Publishers plugins.

Upcoming DITA Webinars

In the next few months we will host a series of DITA-related webinars that will cover almost every aspect of working with DITA in oXygen XML Editor. The first 3 webinars are scheduled as follows:

1. Getting started with DITA using oXygen XML Editor
   Thu, May 26, 2016 8:00 AM - 9:00 AM PDT
   This webinar will focus on introductory concepts of working with DITA documents in oXygen XML Editor, covering everything from creating DITA maps and topics from scratch to basic publishing using out-of-the-box transformation scenarios. You will also learn how to edit simple topics, create cross references, insert images and tables, and how to benefit from intelligent features such as smart paste or validate and check for completeness.
   You can register to attend at https://attendee.gotowebinar.com/register/8739574101053242114
2. DITA reuse and filtering
   Thu, Jun 30, 2016 8:00 AM - 9:00 AM PDT
   This webinar will focus on advanced features that justify your return on investment from using DITA. REUSE is the key word and it can be implemented either directly through content references or indirectly through profiling/conditional content.
   You can register to attend at https://attendee.gotowebinar.com/register/6779464826612680193
3. DITA publishing with oXygen XML Editor
   Jul 28, 2016 8:00 AM - 9:00 AM PDT
   In this webinar, we will explore DITA publishing options available in oXygen XML Editor to produce and customize various output formats such as WebHelp, HTML, PDF, or EPUB.
   You can register to attend at https://attendee.gotowebinar.com/register/7133519665384504065

After these 3, we plan to host 4 more webinars that will cover:

• The support for the new DITA 1.3 standard in oXygen XML Editor.
• How you can use oXygen XML Web Author to enhance collaboration between contributors and reviewers.
• A detailed look into how you can maintain the integrity of your DITA maps and topics by using the validate and check for completeness feature, as well as imposing various editing rules.
• How we create the oXygen User Guide, set up our workflow, enforce project-specific rules, and publish our documentation.

If you want us to cover other DITA-related topics in these webinars, please use the Comments section to let us know.
See you soon!

Collaboration and Document Review in Oxygen XML Editor 18

The reviewing process involves a continuous interaction between authors, reviewers, and subject matter experts.

The visual Author mode now allows you to collaborate more easily and effectively with others through comment threads by providing a new reply to comment action and allowing you to mark comments as being resolved.

Reply to comments

You can collaborate with other members of your team more easily, taking advantage of the improved annotation support. You can now reply to comments added by others and you can also start new comment threads. Everyone that has access to the project can see the comment threads and join the discussion at any time.

Mark as done

The Mark as done option allows you to mark a discussion thread as being completed. This is useful for marking comments that have been addressed, leaving only those that still need some attention.

Watch the following video to see more about Collaboration and Document Review in oXygen XML Editor 18:

XML Three Way Diff in Oxygen XML Editor 18

The new XML-aware three-way file comparison feature helps you solve conflicts and merge changes between multiple modifications of the same file. It is especially helpful for teams that have multiple authors working concurrently on the same documents.

Three-Way File Comparison Support

A three-way file comparison feature was added to the file comparison tool to help you solve conflicts and merge changes between multiple modifications.

 It is especially helpful for teams who have multiple authors editing and committing the same documents. It provides a comparison between a local change, a remote change, and the base (ancestor) revision.

Multiple Algorithms for Three-Way Comparisons

You can use Lines, XML Fast, and XML Accurate algorithms for the three-way comparison feature in the file comparison tool and in the Compare view in Syncro SVN Client.

• Lines - Computes the differences at line level, meaning that it compares the files looking for identical lines of text.
• XML Fast - Works well on large files or fragments, but it is less precise than XML Accurate.
• XML Accurate - More precise than XML Fast, at the expense of speed and memory. It compares two XML files or fragments looking for identical XML nodes.

Integration with version system

The Files Comparison tool can be integrated with file versioning systems in order to visualize changes in a side-by-side manner ans solve conflicts.

Second-Level Comparison

The File Comparison tool now automatically performs a second level comparison for the Lines, XML Fast, and XML Accurate algorithms. After the first comparison is finished, the second level comparisons are processed on text nodes using a word level comparison, meaning that it looks for identical words. This second level comparison makes it easier to spot precise differences and you can merge or reject the precise modifications.

Ignore Nodes by XPath Option

A new option was added on the toolbar of the File Comparison tool and in the Compare view in the Syncro SVN Client. You can enter an XPath 2.0 expression to ignore certain nodes when comparing using the XML Fast or XML Accurate algorithms.

This demonstration will show you how the oXygen three-way comparison feature works and how you can use it with file versioning systems.

What's new in oXygen 18.0 - Webhelp Responsive System

In oXygen 18.0 we released a new HTML5-based online help publishing system called WebHelp Responsive. It has the ability to adapt to any device and screen size to provide an optimal viewing and interaction experience. Nearly all aspects of its layout can be customized and it also includes a variant that allows online users to provide feedback in your documentation.

A short video demonstration covering the basic functionality and customization options is available here: http://oxygenxml.com/demo/Webhelp_Responsive.html.

As an example, our Oxygen 18.0 user's manual is published from DITA using the new WebHelp Responsive system. The DITA 1.3 specification available on our web site was also published using this modern WebHelp system.

For now you can choose between nine beautiful skins for the tiled display:

and nine skins for the tree display:

I hope you'll all enjoy it and we are looking forward to any feedback or improvement suggestions you may have for it.