By Peter Fournier

So, you’re convinced that moving your documentation to DITA XML is a great idea.  The move will increase productivity, enable reuse and allow multichannel publishing to many platforms.  It will also future proof your authoring and publishing – no more getting captured by tool vendors!  Yeah!

But converting your existing documents to DITA can be a daunting task. Documentation is likely the messiest data ever created. It’s very common to discover that all those MS Word documents that should be moved to DITA are not identical from a data point of view:  different documents use different styles, very often headings are actually “Normal” but manually formatted to look like a heading, a numbered list can be a procedure in one place or just a list in another.   From a structured authoring point of view, source documents written in WYSIWYG tools are not your friend.

Because of the complexity of source documents, companies moving to DITA usually choose to get some help getting from a legacy authoring tools into DITA.  There are several routes to choose from:

  1. Over-the-wall conversion
    Send your documents to a company specializing in conversion. They take your documents, convert them, then send them back for QA.  The QA usually involves several conversion and refinement cycles before achieving acceptable results.
  2. In-house conversion with the help of consultants
    This can deliver better results faster if only because it facilitates QA, conversation, discussion and exception handling. Unfortunately, when the consultants leave they take with them the knowledge of exactly how the work was done. You lose precious conversion experience that could have been used in your next project.
  3. In-house conversion using off-the shelf tools
    This can be an excellent solution since you retain the knowledge of how to convert documents to DITA and making the next 1,000 pages of conversion easier to do. Unfortunately, off-the-shelf tools often require expensive cleanup of the source documents and are not sophisticated enough to do a complete conversion, including advanced DITA features, all in one go.

Taking control with Stilo’s Migrate

Migrate smooths the path from messy WYSIWYG documents to advanced DITA XML. Here’s how.

  1. Migrate has the same advantages as over-the-wall conversion
    You upload your documents to Migrate in the cloud and convert them there with help from Migrate/DITA experts. They will assist you with initial conversions and you always pay a fixed rate per thousand words per document. Subsequent cycles through the conversion process are free, in-house, and fast – refine and QA as much as you need, for free.
  2. Migrate has the same advantages as working with consultants
    Stilo’s business model is not about charging per hour as though they were normal conversion consultants. No, Stilo’s business model is assisting you to become your own conversion expert while always being available in the background to help with difficult problems. There is a consulting fee to be paid but it’s not a long term-contract for a fixed amount – you only pay Stilo for the consulting you require to get passed the sticky bits.
  3. Migrate has the same advantages as using off-the-shelf tools
    Migrate has more depth and capability built-in than any other off-the-shelf tool. This minimizes the amount of cleanup required before conversion and enables conversion to DITA with advanced features. Also, Migrate captures the process for converting documents in “rule sets”. Any one rule set can be applied to any number of documents.  So, documents from a specific group or year in your company might require different conversion rules than documents from another group or year.  That’s fine.  Rule sets allow you to permanently capture all of the learning and knowledge about conversion as you go along.

Control achieved!

Stilo’s Migrate is unique in the industry.  It is finely tuned, based on extensive experience over 30 years, to satisfy real business objectives. Among them are:

  1. Proof of concept before commitment
    Migrate allows companies to start their migration to DITA with small bite-sized projects done for minimal cost. If the project is successful companies can expand to larger document suites without entering a new project or dealing with a new company.  Rule sets guarantee capturing experience in-house so that what is learned in converting 30 pages can be applied and refined in the next 100 pages, the next 1,000 pages, and the next 10,000 pages or more. Migrate scales very well within typical budget processes. This is budget control.
  2. Project management
    Stilo’s Migrate model fits in well with standard SW project management. In the last 1,000 pages converted did we experience more or less requirement for consulting with Stilo experts? In the last thousand pages did we have to create new rules at a higher or lower rate than the previous 1,000 pages?  These measures are very similar to standard SW measures such as defects per thousand lines of code.  This is project control.
  3. Source coverage
    You have to convert source documents saved in DOCBOOK, HTML, HTML5, DOCX and MIF. Can Stilo handle all these sources? Yes, of course.  This is technology control.
  4. Learning and knowledge capture
    Are we climbing the corporate knowledge ramp? Can we see our way to no longer needing hand holding from Stilo?  Of course.  That is the Stilo business model.  This corporate business intelligence control.

Control comes in many flavors and at different levels in a company. Stilo’s Migrate helps achieve control at every level.

 

About the Author

Peter Fournier has extensive experience in the BNR/Nortel documentation space. In the late 80’s and early 90’s he studied the feasibility of moving the Technical Documentation to SGML. He later developed, with his team and advanced online help system for Network Management and other software produced by Nortel. The core of the online help software was based on SGML principles of containerization but only had five or six base elements, and a lot of attributes.  It was engineered to be compatible with SGML so the group had no trouble generating valid XML when the draft standard appeared in late 1996 or early 1997.  In 2005 he discovered, with great joy, DITA XML. He introduced DITA to JDSU (now Lumentum) in 2008 and served as DITA manager and technical prime until 2018.  Between 2010 and 2014 he  also found  time to get a startup going and developed software to assist groups of 1 to 20 people to get into DITA and manage all the background complexity, including publication.  As of 2021 he’s back in the DITA space and loving the Stilo philosophy of making highly complex transformation software easily accessible to customers.