TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Re: Flare or Frame as an intermediary for migrating to DITA?
Subject:Re: Flare or Frame as an intermediary for migrating to DITA? From:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> To:"Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 14 Oct 2014 22:15:09 -0700
I think you definitely have it right when you say there are two tasks... I don't necessarily call it information architecture and tagging, but the names aren't important. The first task is to work out what you're going to accomplish, then you figure out how you'll accomplish it. Planning and implementation. I know it's a bit of a boot-strap problem because it's hard to plan without knowing the tools at hand.
I think everybody would agree that you should start with a picture of the result you want. I mean the final output PLUS a general picture of the ultimate publishing work flow. Then ask whether DITA is indeed the format to use. Then look for the tools that will support your format and work flow (maybe no final decision yet, but at least you know there are tools to support your work flow). Now you have a picture of the result you want.
A big part of deciding on your final format includes understanding your legacy content. I think the accepted term is to perform a doc audit. You have to understand how your legacy will map to the final format -- You're currently thinking DITA. Here's where your problem of a 2-page doc that includes task, concept, and reference comes up.
And here's where the "science" ends and the "art" begins... My personal view is that DITA "strongly suggests" a division into task, concept, and reference, but you're free to compose variations on that theme. And really, those topic types are variations on the basic "Topic". In fact, for my current project I only use topics -- not task, or anything else. I sure didn't need more than topic, and it would have just complicated things for me. I'm not saying you should necessarily abandon those other topic types. I'm saying you should be flexible... In this specific example maybe you have hundreds of topics like this and they all have a rigid format... Then maybe you want to make a specialization. OTOH maybe it's a one-off. In that case, maybe you should just use generic "Topic" and not worry about it for that doc. This is probably not helpful for you to hear, but you have to look at your legacy and sometimes be creative about how to apply it to
the DITA world-view. Again, my opinion and I hope anybody who disagrees will chime in.
You mention the webinar I did... Now I have to stand by what I said, right :) I'd have to go over it to see exactly what I said, so let me clarify here. I think it took about a month to do the conversion, and another month to make my help delivery system. But I definitely did NOT write the DTD. DITA is a standard that's declared via the DTD so writing the DTD is none of my business. Further, writing the FrameMaker EDD is not my business... Except that I modified its formatting to produce the PDF look that I want.
Another point about the conversion I did... I wrote the original legacy docs in a startup situation. I owned those docs from the start, and I knew their organization personally. I also knew they stuck to the template pretty well (erm, *really* well). And finally, the writing was already effectively topic-based. So my doc audit came for free.
The Maker conversion table worked pretty well for me. I only tripped up on wrapping graphics in the approved DITA figure/fig group construct. I just let it go, and wrote a pretty simple ExtendScript to clean that up, plus a couple of other easy things to deal with. (I did an earlier webinar on scripting for structure.) Other people said I was nuts, and should have used Mif2Go. What the heck? I wanted to go cold-turkey using only FrameMaker, and it worked ok for me. But the point here is yes, you can use tools to help convert your legacy to XML. If the legacy is already in Maker, then in my opinion you're luckier than many... Assuming the legacy is reasonably rational.
Finally, you mention a third task that is very important... Managing the change for your team. Getting them to embrace structure, DITA, and a new tool. And who knows what else? This is actually way important, and you would probably get a lot of mileage by soliciting buy-in at the beginning when you're fleshing out your vision of the work flow. Tools should be the last question to ask, but this is an area where tools are important. If everybody already knows Maker, there's no necessary reason the force them into a different tool. That's supposed to be the promise of XML -- tool agnosticism. You can use oXygen, and other folks can use Notepad. So what?
Whew! This has become much more long-winded than I intended. I really think you need to start by defining the outcome you want. There's plenty of research to do there, and what you learn will serve you as you move forward. One thing you should try to do is fix a dollar value to it... How much money will all this save you? If the project is big, this value should be big. You may learn that you need outside help -- having an ROI in mind will help you there.
HTH...
________________________________
From: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>; "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Tuesday, October 14, 2014 11:46 PM
Subject: RE: Flare or Frame as an intermediary for migrating to DITA?
So two major tasks in a conversion, it sounds like: information architecture, and tagging.
If I have a 2-page instruction document that combines task, concept, and reference, I've now got to split that out into 3 topics (maybe more) and then apply appropriate tagging to each.
So the structured authoring part is not really automatic, but perhaps the tagging part can be made more so?
I think you said in the webinar that it took you a month to write the DTD and a month to convert 200-300 topics. I could be way off. You also said computers are good at automating tasks. Yes, once you get the data converted they are. Can they help you get the data converted too?
In responding to Mike I said I'm looking for the shortest distance between point A and B. Where are the ways to save time and automate in the conversion process? For all I know, Stilo and DCL can just have a bunch of people who sit there and do the job manually. This kind of business model has worked before! But assuming they don't do that, what processes are they using that you might be able to use in-house? Maybe HTML-to-DITA through the OT is the way to go. I can certainly try that.
It might be that I should regroup and revisit the question when I have more information, if and when that takes place. I'm struggling to ask the right question right now because a lot of it is academic and unknown. But I think you can see what I'm asking.
Thanks, Chris. That was a great webinar, by the way. I encourage you to take another shot at trying to get me to understand this. But if I just don't have enough info yet to ask a good question, then I will accept that.
Steve
PS - I don't know that Frame or Flare as an intermediary would buy me anything. The question only came up because I was thinking, Hmmm, existing skills (among writers), existing licenses, possibly an easier intermediate learning curve than something like, "Okay, let's drop everything and now you're going to learn Oxygen." Or XMetaL, or whatever. AND structured authoring! This is a big task for people, and a big change. But you might be right (as suggested by the others) that it could be easier to just stick with the native authoring environment, whatever that might end up being (if).
On Monday, October 13, 2014 11:22 PM, Chris Despopoulos wrote:
I think the question is a little bit odd. Convert WHAT exactly to DITA? Maybe your best bet is to save as HTML and use the OT to convert that to DITA. I just don't see enough information in the question.
Another consideration... What shape is your unstructured doc in? Does it easily divide into topics? Can you identify points to automatically convert X into a topic, and beyond that, to establish the nesting of topics? Are you sure you have a clear automation path, no matter what tool you use? If not, why don't you just use the authoring environment you plan to stay with?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
