Unstructured Framemaker to DITA

[ramukneevan007]

I need to move my documents from unstructured FrameMaker to DITA docs. Could anyone explain me or point me a link about the step by step instructions to migrate from unstructured to DITA Docs?

PS: I have framemaker 10 license. My preference is not to spend any or more money to do this migration.

Expect Good response.

Thanks,

Naveen

[Russ Ward]

Hi Naveen,

There is no such thing as step-by-step instructions to do this. There are broad concepts, such as:

- Using conversion tables in conjunction with the DITA EDDs/templates to make the conversion

- Using a third-party app such as Mif2Go (http://www.omsys.com/dcl/mif2go_main.htm)... I think that's the right Omni Systems app.

But I am sensing something else... that maybe you need some more knowledge in this area before attempting such a task. This type of migration is a very big deal and a significant effort. To approach it without the proper planning and expertise is a good way to fail in the long run.

Have you done the proper analysis for this? Why the choice of DITA in the first place?

Russ

[The current link to the Mif2go site is: http://mif2go.com/ ]

[ramukneevan007]

Hi Russ,

First of all thank you for the resposne.

My company wants to migrate from unstructured to structured DITA authoring so as to reap the benefits of DITA (Topic Based Authoring, easy management of docs, Content Reuse...and many more).

I have done research and analysis of this migration and understood the concepts of EDD and Conversion tables. But what I need is:

1. What are all the action items required for this migration?

2. Where should I start and where should I end ?

Thanks,

Naveen

[Russ Ward]

Hi Naveen,

I don't mean to patronize, but I'm not sure that you have studied EDDs, etc.  enough detail, otherwise you would have the answers to your questions already. In any case, I need to reiterate that there is no single, concise procedure for this. It is a big effort with endless variations that requires agility and savvy throughout.

I want to also note that while DITA can bring rewards, they are not automatic. In fact, unless you have a clear idea of how you will leverage the various options that DITA provides, the entire effort may result in expense rather than reward.

Anyway, I don't mean to lecture. I'm just trying to provide some background as to why I am not able to answer your questions over a forum post. It is such a big undertaking that one could write an entire book about it. Perhaps someone else can summarize better than me, but that's about the best I can do. In any case, I do think that some form of structured authoring is the first step to entering the 21st century of technical publishing, so I do commend you on beginning this venture.

Russ

[Matt-Tech Comm Tools]

Unless you plan on doing DITA conversions as part of your job description, you will almost certainly spend more money (and absolutely spend too much time) learning the process of converting data from *any* application to DITA than if you have someone else do this for you.

At a minimum, you should consider mentoring (of the paid variety) to learn the process, and help you with the concepts.

One observation: DITA focuses on the topic, and combines them into larger pieces. "Traditional" documentation focuses on the book, or chapter, and breaks these down into smaller pieces. Understanding the basic building units will speed your understanding of DITA's strengths (and weaknesses).

-Matt

Matt R. Sullivan
co-author Publishing Fundamentals: Unstructured FrameMaker 11

[Russ Ward]

Matt,

There is some truth in what you say, but I disagree with the general sentiment. Certainly, if you are a newbie, you might spend up a bunch of time (which equals $$$) figuring out how to do it. However, if done with diligence, that is never a waste. You grow in your professional knowledge and your employer benefits from a higher-skilled workforce. These technologies are critical to the future of technical publishing, so the more people in the field that understand them, the better. You won't get that understanding by paying somebody else.

Additionally, I disagree that you have to pay a teacher, unless you are in some massive hurry in which case the project is likely to fail anyway. I can do conversions in my sleep now, but not because I paid anybody to teach me. It's because once I was just like any newcomer, with a huge job to accomplish and zero knowledge about how to do it. Rather than pay an outsider, I (and couple others) was given the time to figure it out. Sure, it took a good long while that first time, but the professional growth that resulted was a big benefit to everyone involved. And the next time was easier (and there will almost certainly be a next time).

So, I don't mean to be confrontational. I just want to emphasize that the key to success is motivation and time, not a PO for a contractor.

Russ

[Arnis Gubins]

@Russ,

Motivation, Time, Resources ($$) - pick any two...  <g,d&r> 

[Matt-Tech Comm Tools]

Fair enough, but in my experience, convertors are generally under a time constraint.

IOW, as you mentioned, they're generally in a massive hurry. And I agree with you...if they try to convert in a hurry with no help and no prior experience, they're likely to fail.

That was kinda the point of my post. Naveen appears to be under a budget constraint (which, for employees, is also a time constraint). I was pointing out that he should consider the return on investment of honing his conversion skills against getting help in the process.

While much is learned in the process, in my opinion not much is gained in *learning* conversion, if conversions are not to be part of your job description. In addition, conversions are by definition custom work. Each requires analysis of content and mapping of one content model to another.

With regard to now able to do conversions easily, obviously you have done multiple conversions. I'll bet that for you, the first was tougher than it is now, and that you suspected that you'd do more in the future. In other words, you didn't expect to get through the conversion and then move fully into a DITA environment. Also consider that as a developer, you have programming skills that others may not.

Yes, the world will be better for having more and better-skilled folks in it. However, today I'm engaging a QuickBooks expert (because taxes are tough) and a WordPress expert (because if paid for web dev, I'd starve)

I'm sure I'd be better off knowing the underlying concepts of tax, accounting, html and php, but I'm choosing to pick my battles. Speaking of which, your post did come across a bit confrontational to me, and I was only trying to pass on the experience of many of my clients. I don't care to defend my point further, so let's not subject Naveen to an ideological difference of opinion, k?

[Russ Ward]

Matt,

Back to you, I also say fair enough. I think we've sufficiently made our points and I'm good with leaving it here. Thanks for your response.

Russ

[Matt-Tech Comm Tools]

Kudos to Chris Markham for posting excellent resources at the Adobe FrameMaker LinkedIn group:

http://www.linkedin.com/groupItem?view=&srchtype=discussedNews&gid=2204291&item=245338627&type=membe...

-Matt

[Guest]

Russ is giving you good advice.  DITA offers many advantages, but it's not a magic solution.  It's probably not going to be completely expense-free either.

• For topic-based authoring in general, you have to learn to think differently about how to write before you can realize gains. 
• For DITA in particular, your authors will have to become familiar with XML and DITA in order to create topics. Authoring tools such as FrameMaker, DITA-FMx, or oXygen can help, but for practical puposes, they can't hide the XML completely. You'll also have to train authors on DITA elements and attributes, and techniques for using them.
• To get output, you'll need to understand XSLT, CSS, and probably the DITA Open Toolkit and Ant. (DITA2Go is a strong alternative, but it's not in the XSL-based mainstream of DITA activity.)
• To manage your topics, you'll need a decent Content Management System.

As for conversion: I've used both the conversion-table method and Mif2Go to convert unstructured Frame docs to DITA.  In my opinion, Mif2Go is easier to figure out, does a lot of the work for you, and does a better job on the conversion. It is well worth the modest expense. But if you want to use the conversion-table method, I would start by defining a few conversion rules for your major paragraph tags, see what you get, and take it from there. It took me about 35 iterations to get a reasonably decent conversion table for my tag set.

Ether way you will almost certainly have to make some manual touch-ups.

(EDIT) If you're looking for information on how to create a conversion table, you'll need the Structured Application Developer Reference (Chapter 4).

http://help.adobe.com/en_US/FrameMaker/9.0/StructuredDev/Structure_Dev_Reference.pdf