September Book Club recap: Converting Content to DITA

We discussed chapter 11: Converting Content to DITA of DITA Best Practices at the September 28th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Intel, and Viewpoint.

book club

Some of the members had converted to DITA years ago and some of the members are doing it currently. We shared stories about implementing DITA and compared them to what we had read.

What was your company’s motivation for switching to DITA?

  • Lots of available tools
  • Open source architecture
  • Content reuse

How did you convert?
Most of the members converted to DITA manually by copy/pasting from their old tool into their new DITA tool. Leona particularly remembers a huge spreadsheet logging the progress of what was converted and what wasn’t.

Did you have to publish while converting?
None of our members had the space in their schedules to devote exclusively to migration. It was a gradual process of conversion, mostly scheduled between releases, with some writers on a team continuing to use an old tool while their teammates moved onto the new DITA tool.

Did you have a team devoted to conversion?
We all had a nice chuckle at the huge pilot team suggested in this chapter. Many of the members had little to no in-house DITA expertise when converting. As Marya noted, DITA is often aimed at large teams but is adopted by small teams, too. Those small teams are doing what they can, with whatever expertise they have and whatever training they can get.

What is the most important training you need while you are converting?

  • Topic types
  • Tagging
  • Maps
  • Folder organization

What are some good ways to get that training?

  • The “automatic” training you get by using a tool that validates against a DITA DTD is a great way to learn as you are converting, by warning you when you are doing something that DITA doesn’t allow.
  • Take a hint from “mob programming” and sit down with your co-workers to write some DITA topics as a team so you can discuss strategies and learn together.

Some things to remember while converting:

  • If you have a lot of topics in a fairly flat folder organization, you’ll need a good naming convention for your topics. Try keeping the name close to the title of the topic so you can find your topics more easily.
  • Converting HTML tables to DITA is time-consuming. If you are converting a lot of reference docs, make sure you allow time for it. If anyone has come across a solution that makes this easier, please let us know in the comments!
  • Start a book club of your own! You can learn so much by reading a beginner DITA book and discussing it with others in your DITA community.

Couldn’t make it to the meeting but have something to add? Want to share a story about your DITA conversion? Tell us in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:
Where: Viewpoint, 1510 SE Water Avenue
When: October 26, 2016 from 5:00 to 6:00 pm
What: Chapter 12 of DITA Best Practices
RSVP: Email

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.