RE: Flare or Frame as an intermediary for migrating to DITA?

Subject: RE: Flare or Frame as an intermediary for migrating to DITA?
From: Rebecca Officer <Rebecca -dot- Officer -at- alliedtelesis -dot- co -dot- nz>
To: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>, 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>
Date: Fri, 17 Oct 2014 00:22:32 +0000

Hi Steven

We're in the process of converting about 20000 topics to DITA from unstructured Frame, so I'm finding this conversation very interesting.

I've got a few thoughts to add.

First, you do need to do information architecture, at least enough to figure out what your structure is going to look like and which DITA elements you're going to use. Depending on what your documentation's like, that may not be a big deal.

Learning structured writing is quite a change, but you're right that it's independent of DITA. If people are still working on the docs you might convert, get them doing structured writing ASAP. It'll make converting those docs much easier.

That said, I'm finding that there are at least two distinct roles in a DITA conversion: developer and author. Two of us are sharing the developer role, and that's complicated as. Between us, we've had to figure out the structure, learn MIF2Go, script various things to fix the files, edit the EDD, figure out how the CCMS works, and figure out publication processes and tools.

The others in the team have just started writing new docs in DITA, and that's much simpler than the development, even though it's a new paradigm. DITA emphasises simplicity, so as writers we're not finding the authoring side as hard a change as I expected. We did get decent training (thanks, Matt Sullivan :-)), and we haven't gone live on the CCMS yet, so we've separated out that from learning DITA authoring. But from a writing point of view, it's pretty good.

Cheers
Rebecca

-----Original Message-----
From: techwr-l-bounces+rebecca -dot- officer=alliedtelesis -dot- co -dot- nz -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+rebecca -dot- officer=alliedtelesis -dot- co -dot- nz -at- lists -dot- techwr-l -dot- com] On Behalf Of Janoff, Steven
Sent: Friday, 17 October 2014 7:35 a.m.
To: Chris Despopoulos; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Flare or Frame as an intermediary for migrating to DITA?

Thanks, Chris, for all this great information. It's a lot, and I will need some time to digest it. I appreciate your taking the time to write these things and express them.

And it's certainly different than what I had expected, but as I read it over, it starts to make sense.

Apologies too for misquoting you on the webinar. Yes, after what you mentioned below, I did in fact remember that you said it had taken you one month to convert and one month to build the delivery system. For some reason I had also thought you'd "rolled your own" DTD, but in retrospect I believe you merely suggested that someone could do that if they wanted more control over the output. This might have been what spawned the separate discussion by Maxwell of the fellow who had written a really good custom DTD (or EDD) that allowed a group of non-technical authors to train up on the tool and their task in a week. But these were two separate discussions, so I guess I just extrapolated your own suggestion and thought that you had in fact written your own DTD, when clearly you did not.

One thing that projects immediately is your suggestion that the current view points to DITA but not necessarily. I'm not sure I understand what the other options are. I know that S1000D tends to be for defense-related work, and that DocBook is built on the older book model and folks are trying to move beyond that. But I know you're not necessarily suggesting that these are the alternatives you have in mind, and you might be thinking, "Maybe you don't need to go to DITA or XML, maybe you can stay in Flare and Frame." If this suggests any thoughts to you for clarification, I'd be all ears.

I also realized, before your note came in, that I was confusing structured authoring with DITA, and it dawned on me that they are two very different things. I've read about and/or used each over these past 8 or so years (or more), but it was only now that I realized that structured authoring refers to the writing technique, structured writing, that was part of Information Mapping as developed by Horn in the late 60's, I believe -- long before publishing software and long before even PCs. And I remembered that DITA was sort of IBM's "answer" to structured writing, in that it imposed structure on the writer's efforts but also gave an advantage that by tagging the data you now had access to the power of computerization, as you described in the webinar. (DITA just reduced the number of topic types from 7 in IM to 3 or thereabouts, if I remember right.)

It occurred to me that writers could be taught structured authoring/writing LONG before DITA adoption, in their current tools -- MS Word (heaven forbid), FrameMaker, Flare, etc. And once they had a good grasp on that, THEN you could go for the conversion to DITA and XML -- which means training in the native XML editor in the adopted CCMS environment, if that's the way to go.

Those are really the "two tasks" I was referring to: structured writing ("information architecture" was a misnomer there), and the conversion to DITA/XML via tagging/markup. Maybe some of that could be automated, maybe not (the tagging part, that is). But the alternative is to get a team of writers to learn BOTH structured writing AND developing in DITA/XML, a new XML editor, and a CCMS all in one go. So I was thinking that perhaps you could break that task into two and get non-technical authors there in two distinct steps, focusing on one at a time. After all, when structured writing was developed, it was just a way to improve information that was basically on paper. It's a distinct skill. And then once you have your content structured (prior to tagging), the conversion part could be much easier.

I think that's about as much as I can venture for now, in terms of adding anything to the conversation. As I say, I'll study this more, and if I have anything useful to add, I will try again.

Meantime, thanks again for the time and effort you put into conveying these things to me and really to all of us on this list.

Steve

PS - In researching these things recently I had also come across a tech writer named Kai Weber -- maybe he's on this list -- who was advocating structured authoring in even MS Word, without DITA or XML -- I believe he gave a presentation on this at this year's STC Summit, although I haven't had a chance to view that yet (but I have read the brief article overview). So there might be a case for this approach, of teaching structured authoring prior to DITA adoption, maybe without the necessity of that adoption.


From: Chris Despopoulos [mailto:despopoulos_chriss -at- yahoo -dot- com]
Sent: Tuesday, October 14, 2014 10:15 PM
To: Janoff, Steven; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Flare or Frame as an intermediary for migrating to DITA?

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as rebecca -dot- officer -at- alliedtelesis -dot- co -dot- nz -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Re: Flare or Frame as an intermediary for migrating to DITA?: From: Chris Despopoulos
RE: Flare or Frame as an intermediary for migrating to DITA?: From: Janoff, Steven
Re: Flare or Frame as an intermediary for migrating to DITA?: From: Chris Despopoulos
RE: Flare or Frame as an intermediary for migrating to DITA?: From: Janoff, Steven

Previous by Author: Re: Has technical writing fallen from grace?
Next by Author: RE: Meeting minutes for an HR project
Previous by Thread: RE: Flare or Frame as an intermediary for migrating to DITA?
Next by Thread: Re: Flare or Frame as an intermediary for migrating to DITA?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads