My most technical day of the LavaCon 2012 conference occurred on the final morning when I focused on working with DITA by attending two sessions: “Migrating to DITA: How Automated Conversion Works and Why it Matters” (with Patrick Baker of Stilo International) and “Collaboration and Instantiation: Engineering Content in DITA XML” (with Cheri Mullins, of Mullins Consulting, discussing her work at AMD).
Migrating to DITA: How Automated Conversion Works and Why it Matters
Presenter: Patrick Baker, Stilo International
With the huge volumes of information that are involved in a typical conversion, automation is a necessity to be successful in working with DITA. Documentation is more structured than the content owners realize, and automation is not as formidable a task as it might seem.
Patrick discussed the process of conversion to DITA in terms that I am familiar with–as a software development project of sorts. As with a software project, you can choose to use Waterfall, Spiral, or Agile methodologies. Although Agile is getting all the buzz, Patrick seemed partial to the Spiral methodology, which he described as somewhat similar to Waterfall, but still allowing new requirements to be incorporated iteratively.
With DITA conversion, just as with a language translation, you must use the context cues to provide information. Thus, the string “12/01/1979” has one meaning when found in a Canadian newspaper (January 12, 1979), but a different meaning when found in an American newspaper (December 1, 1979).
According to Mark, once you have the correct context, you can set up regular expressions in your scripts to do the conversions. Regular expressions are programming constructs that recognize patterns in strings. Inevitably, you will have to do some post-conversion cleanup.
I asked if it was better to do pre-conversion cleanup in order to save on post-conversion cleanup in working with DITA. Patrick said that it is almost always worthwhile to work on making the pre-conversion material as clean as possible.
Patrick is an accomplished programmer who is very knowledgeable about DITA conversions, and text-processing issues in general. Take a look at some of the resources and services offered by Stilo International.
Collaboration and Instantiation: Engineering Content in DITA XML
Presenter: Cheri Mullins, Mullins Companies
Cheri Mullins is unmistakably a Texas gal, arriving on the scene with a black Stetson, which she gave away at the end of the presentation (or tried to). Her work at AMD was the focus of her talk about authoring engineering content in DITA.
Some takeaways from this session:
- Yes, authoring can and does take longer in DITA than using traditional methods. The benefits of DITA arise from consistency and reuse.
- Writers on your team have to be on board. You cannot have writers doing things like correcting the output after transformation. You must clearly require that the source must be corrected. The way Cheri’s team has their build scripts set up, running the transformations does not take very long, so saving time is not an excuse.
- AMD uses JIRA, and the content created in JIRA can be converted to DITA. As an aside, for those who have not used JIRA, it is one of my favorite programs ever—a bug-tracking program produced by Atlassian. See: www.atlassian.com.
- Cheri’s team uses the Oxygen XML editor with a MathFlow plug-in. If I had a chance, which I still may have, I would ask more about the benefits of Oxygen as an authoring tool for DITA.
Both of these sessions gave a sense of what it is like to be in the middle of a DITA project, both at conversion and over the long haul, and the challenges you will inevitably encounter while working with DITA. They were highly practical, nuts-and-bolts sessions that eschewed theoretical justifications to talk about how converting to and authoring in DITA really works.
Cheri on Twitter: @cherimullins
