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.
Hi Steve. I'm coming in late to answer your original question.
Mostly I'd just me-too Mark Giffen's first post. I found myself
nodding at almost every paragraph.
I would want to know, have you used a CCMS with a built-in XML
editor or a third-party XML editor such as oXygen, XMetaL, or the
like?
Editor: We use Arbortext but are likely to move to Oxygen in the next
year or two.
For some tasks where Arbortext is weak we also use the jEdit text
editor with the XML plug-in.
CMS: We use the TortoiseSVN front-end to Subversion, mostly just to
save snapshots and work-in-progress. Our coders might move to Git and
if they do we will too.
So you might have legacy content in any of these formats: (text;
Word; unstructured Frame; ID; Flare)
Therefore five different conversion paths.
Would it make sense to use either Flare or Structured FrameMaker as
your intermediary to convert unstructured content to XML/DITA and then
export to your CCMS with editor?
You could pilot test some conversions to see how much time it would
take or save to go via Frame or Flare to get to DITA and Oxygen (or
whatever). But if this is your roadmap:
* Steve and another writer do the bulk of the conversions and become
the in-house experts on DITA and Oxygen.
* Initial conversion results in manuals that 'build clean' and
produce roughly comparable output to the pre-conversion sources.
* Other writers have enough competence with Oxygen to tidy up
converted topics and add new topics with support from the experts.
... detouring via Frame or Flare just delays your coming to grips
with DITA and Oxygen.
Personally I would get comfortable with a good text editor with regex
support (such as TextPad or jEdit). This will help you to become
familiar with your source documents and also with the typical tag
structures in your new DITA topics.. If they're very well-structured
you will be able to do more in the way of automation, otherwise expect
to do a lot of manual cleanup.
I know there are companies that specialize in data conversion, but if
you go the in-house route, I'm wondering if anybody on the list has
had experience with this kind of thing, and what you found.
If you go with a conversion vendor, make sure you agree with them what
constitutes a converted topic. The minimum would be a topic that
builds cleanly (no errors or warnings) and produces complete output.
Yet this could still leave you with a significant amount of work to
bring it to a level that meets your quality standards and yields the
benefits that you hope to get from DITA. There might be some ideal
combination of paying a vendor to do the brute-force work and
finishing the rest off in-house.
To give a specific example: One of the publication sets I look after
was converted from SGML to DITA by a partner company who had recent
experience of converting similar material They used an in-house
script to produce Mixed/Combo (that is, un-typed) topics. This made
the conversion much simpler as this topic type is very forgiving in
terms of validation. If the conversion tool had been told to create a
DITA task for each procedure, a lot of the content would have been
'quarantined' and marked as requiring manual cleanup because it didn't
fit the fairly strict structure of the topic type.
Other problems:
* The converter produced generic, meaningless file names and topic
IDs. Names like cexu-overview-event-collection.dita are a lot more
usable than cexug291.dita, cexug292.dita, cexug293.dita, but changing
them after the fact is a lot of work.
* In-line links were not converted to DITA-style 'related topics'
links These had to be done case-by-case.
My point is that old content that's been minimally 'converted to DITA'
can still require a lot more work.
Finally, some more background reading: This Techwr-l thread from July
last year covers similar ground and there are some good tips from Yves
and others:
Cheicken and eggs scenario for structred writing http://www.techwr-l.com/archives/1307/techwhirl-1307-00142.html
You could contact the OP and see how his new DITA implementation is
going.
Good luck! I find this sort of work really interesting. Let us know
how you get on.
--- Stuart
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
