SAEAF Editing Crew: Update Page for Karen Smith
SAEAF DITA Conversion Experience
by Karen Smith (updated 2009-12-14)
Link to main SAEAF Editing Crew page: http://wiki.hl7.org/index.php?title=SAEAF_Editing_Crew
This section describes my progress with the SAEAF DITA CONVERSION project. You can refer to this section for when you work on future DITA projects.
SAEAF PHASE 1 PROJECT SCHEDULE
File:SAEAF project timeline.pdf
2/18 - Finish converting the SAEAF Intro to DITA format by end of tomorrow (on target). Week of 12/21 - Convert the ECCF doc into DITA format. This document is very close to being finalized. Save late revisions for phase 2. Week of 12/28 - Finish converting the ECCF doc (if more time is needed) and convert the BF document to DITA. Charlie is reviewing BF and will have it ready next week. Governance - ?
A few options:
- A) I wrote a stub topic on Governance in the SAEAF DITA document. When the Governance doc is available, I could create a PDF of the Governance doc and link to it from the Governance DITA topic.
- B) Save converting the Governance doc to DITA for phase 2.
Otherwise, I will need the first three weeks of January to edit the Gov doc, update the outline, create the ditamap and dita files, and do the actual conversion. (For ECCF and BF, I've already completed these preparatory steps except for the actual dita conversion, which is mostly a copy, paste, insert, and build operation.)
Due dates for ECCF and BF "final" versions -- no later than week of 12/21, the earlier the better (for phase 1).
COMPLETE DITA CONVERSION STEPS: I followed these steps to complete the SAEAF DITA conversion project.
PREP PHASE
- Installed and practiced with the DITA tools.
- Created concept maps and DITA outlines.
- Wrote the SAEAF DITA PROJECT strategy.
- Set up a project schedule.
- Gathered all of the graphics from the PowerPoints and Word documents.
EDITING PHASE
- Edited several iterations of the Word documents and the PowerPoints (once).
- Updated the Word and PowerPoint documents with the editorial changes and reviewer comments.
- Wrote some new content.
DITA CONVERSION PHASE
- Revised several graphics.
- Created bitmap versions of the PowerPoint vector graphics. Used PNG for the vector graphics and JPG for the modeling diagrams and other bitmap graphics.
- Created the ditamaps and dita files using Information Architect Workbench.
- Wrote the high-level DITA topics including a non-technical executive summary topic.
- Converted the Word files to DITA using a special procedure.
- Copied the text into the SAEAF DITA document.
- Cleaned up the text, retagged text, inserted graphics and links.
- Ran builds, checked output, fixed errors.
DECEMBER 14, 2009
I wrote the highest-level topics and expanded the first topic in the executive overview with a less technical explanation of HL7's expertise in interoperability and why it is important for healthcare organizations. Then I started the dita conversion by dragging and dropping from Word into the dita documents. I converted the executive overview and the first 10 pages of the SAEAF Intro. It was slow going, as the drag and drop technique only works for standard Word styles, so I ended up doing some copying and pasting as well. It also required manual cleanup as it inserted extra paragraph tags and some of the special characters (apostrophes and quotes) got messed up in the translation or it inserted extra spaces next to commas and parentheses. The drag and drop technique works for standard paragraphs and bulleted lists, tables, jpg graphics, BUT not for fancier formatting, nested lists, or vector graphics. Then I tried the dita conversion technique that Cliff sent me a few weeks ago. It worked! Although I still have considerable manual cleanup and copying to do, at least, the Intro document is now one, LONG dita document. Copying from one dita doc to another is much, much faster.
The dita conversion technique that Cliff sent me involves opening the Word doc in Open Office Writer and saving it as a Docbook document. Then you use the docbook2dita plugin from IBM to the DITA Open Toolkit to convert the docbook document to one long dita document. (My husband installed this plugin and used an ant script to run the conversion.)
DECEMBER 16, 2009
I edited the ECCF Word document, revised and inserted the graphics. Also tested various sizes for the graphics in the html and pdf output formats.
JANUARY 4, 2010
- Finished editing the ECCF document by 12/28 and the BF document by 1/1/10.
- Updated SAEAF project timeline.
- Currently putting the ECCF material into the DITA document.
JANUARY 7, 2010
- Sent XHTML and PDF output for the SAEAF DITA project to the ArB group.
JANUARY 16, 2010
- Published SAEAF DITA document in XHTML (TOCJS)and PDF format for the Phoenix WGM conference and ArB.
