5 writers, 2 software products.
1 mature product -- a universal printer driver -- has HTML Help and a User Guide in unstructured Frame. Help is translated into 31 languages, the User Guide is not translated.
The 2nd product -- network printer management -- has just had its first release. A User Guide in unstructured Frame is being used for Help. Translated into 6 languages.
The plan is to single source both products and output HTML for Help and PDFs for User Guides.
We had 3 days of DITA authoring training with Anna van Raaphorst and Dick Johnson of VR Communications. They helped us install the Open Toolkit and walked us through the garage and grocery shopping examples. Anna and our printer driver SME discussed the structure and organization of the existing Help. We then started rewriting that Help in DITA during the class and the author has been working on it since then.
We have signed up with DocZone for hosted content and translation memory management. As I mentioned, their team will be working on analyzing our data and loading it into the system so that we can start working from a database and implementing workflow processes. Wednesday will be their first day on-site, so I hope to have an update for the meeting on what we have accomplished.
General guidelines for structured-to-structured migration
http://www-128.ibm.com/developerworks/xml/library/x-dita8a/ - "Migrating HTML to DITA, Part 1: Simple steps to move from HTML to DITA"
You don't have to go all the way to "pure" DITA topic files in one step. If you're currently in unstructured Frame (or any chapter-based model), you can always go to chapter-based DITA files where you have nested topics. This is perfectly valid DITA and can be a good interim target for a conversion if you don't have the time to restructure and rewrite. Most documentation sets will fit into DITA's topic structure (even linear non-topic types of documentation). You won't really gain the full benefits of all that DITA has to offer, but it will allow you to work in structure/XML while keeping your filesystem and other processes intact while you test the remainder of the conversion and wait for another window in your schedule.
If you're migrating from unstructured Frame, take the time to get your conversion tables as close as possible to generating real DITA .. don't rush things.
After running your conversion table and applying the new EDD/template .. keep the files in FM binary format as long as possible. There are all kinds of things you can quickly do in Frame across a whole book of files that are much more difficult to do once you're in XML (unless you're an XSLT wizard).
I highly recommend getting a copy of FrameSLT (http://weststreetconsulting.com/WSC_FrameSLT_Lite.htm) .. this plugin lets you do XSLT-like processing in Frame and is a huge time saver!
This writeup describes a strategy derived from the conversion of heavily-interlinkined 24 HTML documents to 35 DITA topics wrapped by three DITA maps. Some of the details in this writeup are HTML-specific, but the general concepts apply to most any conversion.
I had heard this advice before, but until I did a project in DITA, I didn't fully apreciate the reasons:
DITA is like HTML links on steroids. Imagine having to manage all of your HTML links manually. DITA is much worse. You have:
Metadata tags in filenames
Topic type encoded in directory name (concept/) or in file name (c_xyz, xyz_concept)
Topicrefs that are sensitive to location and name
Conditionalized topicrefs that depend on the metadata, as well as conditionalized content
plus image links, topic links, and external references
So you need some kind of CMS to work effectively. Inexpensive choices:
There are 4 kinds of activities in the process:
The ideal starter set for an agile process would look something like this:
Here are the columns for the worksheet:
Source document -- topic type -- subject (topic name) -- metadata columns
You want subject names here, not file names:
While doing this high-level analysis, it's a good time to think about topic titles:
Topics that have identical idenifiers are candidates for merging. Inspect the source documents to see:
Process the merge-candidates first, or flag them so you look at the other source docs when you get to them:
Note: Sorting the list and then resorting it could conceivably lose information. After the original analysis, the topics will appear in the table in the same order they appear in the source files. That makes it easy to step through the source file, extracting topics. After sorting ,
Work in the source document format as long as possible, to minimize the confusion factor
Flag places where conditional metadata needs to be added:
Flag places where conrefs need to be inserted:
Run h2d on the HTML pseudo topics to create DITA topics