"Real Life" Migration to Structured Doc

Wed Feb 1 04:14:28 PST 2006

I generally have to agree with what is written below, but I have to take a minor exception on (a) regarding 'the line that you can do it with DITA or DocBook'. Out of the box does a good job, but unfortunately the 'good job' is at scaring people away. That being said, I'll have a freebie of a pretty good DITA lite template with documentation and more for the world at large in a week or so. I'm literally waiting on a few scripts, a test and some docs and then it's ready. Sure I've needed some updates to the software and I'm pushing Frame in directions it doesn't normally like to go, but in the end I'll have something that works in 7.2 and does 99% in 7.1 as well.

It's going to be distributed via my website and updates will continue to be rolled out. It does use some inexpensive third party software and is a subset, but it's pretty solid.

The exception I have is that you need to consider what you are willing to adapt in your content as well. Just because it has 'always been written that way' doesn't mean you have to stick with it. Sometimes it's worth sacrificing or changing things to save time/money on your deliverable. If you can manage to use a DITA standard then you are in luck later when changes are needed or third party tools have to be invoked.

I'm off to a client site, but I'll post more info on the DITA lite template set soon.

I'll happily offer to provide an online venue where I can show it in use if people are interested. Email off list if you would like to have me present a 'how to use the template' session in a live online video presentation. If so I'll email you more info and, if there seems to be enough interest (say over 20 emails to me) I'll send a quick note to the list.

Bernard

Bernard Aschwanden
Publishing Technologies Expert
Publishing Smarter

bernard at publishingsmarter.com 

www.publishingsmarter.com  

-----Original Message-----
From: framers-bounces+bernard=publishingsmarter.com at lists.frameusers.com [mailto:framers-bounces+bernard=publishingsmarter.com at lists.frameusers.com] On Behalf Of Marcus Carr
Sent: Tuesday, January 31, 2006 6:12 PM
To: framers at lists.frameusers.com
Subject: RE: "Real Life" Migration to Structured Doc

Dominick A. DeFlorio wrote:

> We must move to structure to meet our future XML goal, but are 
> unfamiliar with both the transition and method to do so.  We are also 
> unfamiliar with the possibilities and cost involved. We are merely 
> looking at all of the possibilities and the long term value for our 
> dollar.

Here's how I'd do it:

a) Design the structure - if you aren't experienced, don't do it yourself and don't buy the line that you can do it with DITA or DocBook. 
Get a professional to do proper analysis and design, including documentation about how to use the DTD or schema. This is a critical step - don't scrimp here.

b) Save all of your data out of FrameMaker as XML - don't use FrameMaker as a migration tool because if your structure evolves based on infrequent cases, you'll end up spending too much time trying to re-baseline your dataset.

c) Use XSLT to convert from XML to your target structure - if you find that you need to make changes, make them and re-run the whole dataset, so you can be certain that all documents are consistently handled. Get help with this if you're not experienced, otherwise you'll get in a mess. Be prepared to also make changes to the data manually - the alternative is to loosen the structure in the DTD or schema, but that's a last resort. Make the data consistent, and be ruthless about it. While you're at it, learn not to be scared to work with native XML - angle brackets don't bite.

d) Build the FrameMaker application - concentrate your own efforts on the part of the process that you're most familiar with and learn the parts that will give you the most benefit.

e) Train your users - give them as little information about XML as you can get away with. All they need to know is that there's a mechanism in the background that ensures that the documents are structured consistently with the rest of the dataset.

Items a) and c) will cost you money, but it's well spent. Do it properly from the start and you'll only do it once - try to do it on the cheap and you can spend the money next time around. I've seen it more times than I could count in the 15 years that I've been involved with SGML and XML conversions. Plenty of very bright people have tried to migrate to structure on the cheap - so many smart faces, so much egg.

--
Regards,

Marcus Carr                      email:  mcarr at allette.com.au
___________________________________________________________________
Allette Systems (Australia)      www:    http://www.allette.com.au
___________________________________________________________________
"Everything should be made as simple as possible, but not simpler."
        - Einstein
_______________________________________________

You are currently subscribed to Framers as bernard at publishingsmarter.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit http://lists.frameusers.com/mailman/options/framers/bernard%40publishingsmarter.com

Send administrative questions to lisa at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.