Re: Resources for learning Structured Writing?

Subject: Re: Resources for learning Structured Writing?
From: "Stuart Burnfield" <slb -at- westnet -dot- com -dot- au>
To: "Techwr-l" <techwr-l -at- lists -dot- techwr-l -dot- com>, "Janoff Steven" <Steven -dot- Janoff -at- hologic -dot- com>
Date: Fri, 24 Oct 2014 18:11:59 +0800

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

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
You could contact the OP and see how his new DITA implementation is

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 |


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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Re: Resources for learning Structured Writing?: From: Stuart Burnfield

Previous by Author: Re: UI Elements
Next by Author: Re: Documentation collaboration - best practices and tools used?
Previous by Thread: RE: Resources for learning Structured Writing?
Next by Thread: RE: Resources for learning Structured Writing?

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

Sponsored Ads