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.
On Fri, Jul 26, 2013 at 4:14 AM, Stuart Burnfield <slb -at- westnet -dot- com -dot- au>wrote:
> (...)
>
> 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.
>
[Yves] >>> Instead of saving the Word file as (Microsoft) XML, you could
also try Eliot Kimber's Word-to-DITA transformation Framework:
1. Open the Word files in FrameMaker.
2. Use mif2go (www.mif2go.com) to set up your conversion (basically a style
to element mapping), for example:
- heading* = title
- bulleted list = ul li
- instruction = cmd
- heading 4 = section
3. Save the FM file as DITA.
> - Use MS Excel as an intermediate step to convert large tables to DITA.
>
[Yves] >>> That's not really required. Some DITA editors, such as oXygen
XML Author and FrameMaker 11, have a "Smart Paste" function, which handle
tables very nicely, even more complex tables with merged cells.
>
> 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.
>
[Yves] >>> Well, actually, you can, depending on the type of structure
information which needs to be added. Metadata is very important if you use
DITA. In a topic, you can add metadata in the <prolog> element, which can
contain things like the name of the author, the creation and modification
date of the topic, the product name, the version of the topic etc. MIF2Go
can add this prolog to each topic during the conversion.
Still, you will have to check your content after the conversion and
restructure it (a bit, YMMV). For example, suppose you have this paragraph
in the original text:
"Click on Preview. You should see that this output creates a PDF of the 3D
view only."
After conversion, you will get this:
<step><cmd>Click on Preview. You should see that this output creates a PDF
of the 3D view only.</cmd></step>
This is *valid* DITA, but not well-structured yet. You need to restructure
and refactor this to get something like this:
<step><cmd>Click <uicontrol>Preview</uicontrol>.</cmd>
<stepresult>You should see that this output creates a PDF of the 3D view
only.</stepresult>
Conversion can be automated; restructuring/refactoring cannot because you
actually have to read the text and then decide that, in this case, the
second sentence is the result of the instruction in the first sentence. In
other cases, however, the second sentence may be an example (stepxmp), a
tip (note type="tip"), or just some more information about the instruction
(info).
Cheers
--
Yves Barbion
www.scripto.nu
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
