Re: Cheicken and eggs scenario for structred writing

Subject: Re: Cheicken and eggs scenario for structred writing
From: Stuart Burnfield <slb -at- westnet -dot- com -dot- au>
To: Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 26 Jul 2013 10:14:33 +0800 (WST)

And I heartily second Chris's suggestions.

Do a thorough stocktake of your current docs. Look for reusable information such as common options or boilerplate sentences that can be defined once.

Go through every heading and decide whether it should be a standalone topic or simply a subheading within a topic. Classify each topic as Task (procedure), Concept or Reference or a mixture of different types. In my case I did the first pass literally with pencil and paper: I marked up each heading in a hardcopy with T, C or R. Mixed topics probably need to be split into separate topic types. For example, T/C would indicate a task with a lot of conceptual background mixed in, which might be restructured as task and concept topics that link to each other.

In DITA, cross-references to a figure or another topic are implemented through unique IDs. You could come up with a naming scheme for IDs.

Start experimenting with a conversion process. It would be a mountain of work to manually paste your Word content into skeleton DITA topics. There won't be a simple single-step 'Save As DITA' but you should be able to at least semi-automate the process. For example:
- Save a Word document as XML. This creates a text file with Word formatting mapped to generic tags. Use scripts, macros or regular expressions to convert all generic XML tag s <foo> to actual DITA tag <bar> and to delete unwanted MS Word fluff.
- Use MS Excel as an intermediate step to convert large tables to DITA.

As Chris says, you can't magically add structure information that isn't there in the original, but you can automate a lot of the grunt work.

Good luck.


Chris Despopoulos said:
> One step not to skip is to generally audit your current content. Look for compatibilities/incompatibilities... Look for how the content should map to DITA. You can find lots of information out there to help direct this level of the effort.

I have to second Yves' suggestion for pre-defining your procedures, concepts, reference topics if you plan to use those divisions. Typically, you will go from a given heading level to any one of those... That means you have a 1-to-many translation. In effect, you're adding information into your source. There's no way to increase the resolution without manually doing the work. So you should go ahead and start on that. It will teach you a lot about your content, and ties in nicely with an audit anyway.

New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more:


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 @


Previous by Author: Re: Master Documents in Word
Next by Author: Re: Cheicken and eggs scenario for structred writing
Previous by Thread: Re: Cheicken and eggs scenario for structred writing
Next by Thread: Re: Cheicken and eggs scenario for structred writing

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

Sponsored Ads