Introducing DITA and Content Management Into Your Publishing Process

Home/Publications/Best Practices Newsletter/2008 – Best Practices Newsletter/Introducing DITA and Content Management Into Your Publishing Process
[level-visitors] You must login to view this article.




October 2008

Introducing DITA and Content Management Into Your Publishing Process

CIDMIconNewsletterMark LeBlanc, XyEnterprise

DITA is a powerful standard for creating and managing content. When you combine it with a powerful content management system, the business benefits can be enormous, ranging from cost savings, greater reuse of developed content, and faster time-to-market.

Sounds great, right? It is great! So how do you get from initial enthusiasm, “Hey this DITA thing sounds neat”, to the point where you can say, “You mean all I have to do is push this button and I get my publication in PDF, HTML, Help, and Word in 31 different languages?!”

This article will show you how the right processes and a DITA-oriented content management system can help you get started.

Being a software developer for many years, I don’t like chaos. I know that may seem like a contradiction given the way technology constantly changes, but I have learned that the best way to adopt new technology, whether an information architecture or a CMS is to take deliberate steps in a consistent direction while keeping your options open. I have heard many content professionals ask, “Should I get some experience with DITA first and then think about content management, or should I move toward content management first and then add DITA?” There are pros and cons either way. However, if it were my job to advise customers about how to proceed, I would say…

First, invest in a content management system and learn first-hand how it works. A good content management system not only stores content but also helps you identify and gain control of the business processes that you will need in place to produce publications. You will want to take full advantage of your content management system and adapt it for your business needs. And a good content management system can add value by helping you get from your unstructured world to a structured one, thus actually helping you adopt DITA.

Second, start working to structure your content in DITA. DITA is a standard that can be used in many ways—you will want to use it in ways that support your particular deliverables and business goals.

Third, examine your delivery, translation, and publication processes to understand fully the way that DITA-managed content can return business value and provide substantial ROI. The folks that I have worked with, who have paid close attention to these processes, are seeing returns on investment on the order of 75 percent.

Of course some sites still start by developing data models and creating content using the old fashioned “hard work and a hard drive” methodology. They start with DITA from the get-go and after creating a large number of topics that need to be combined into a collection of publications, they then realize, “Hey this DITA stuff is pretty powerful, but we’d better get ourselves a content management system, or we will spend more time managing the content on our file system than we do actually creating the content.”

Here is one all too familiar scenario that I like to call the DITA Disaster.

DITA content is created by many people and is all over the file system—it’s the wild, wild, west. Those charged with working with DITA have done just that—all in their own way. What’s contained in a topic is different depending on who was writing at the time. Some content is on a network server and some is local—for the same publication. Often references don’t exist or if they do, the links to them are wrong or out of date. A lot of content, especially the maps, suffer from copy and paste problems. These folks weren’t worried about consistency or content maturity. In fact, just the contrary, they were encouraged to experiment and try different things. And now they have a bit of a disaster on their hands.

I have one customer who had 300 different topics all named intro.xml. These topics were only differentiated by the sub-directory in which they were placed. I guess their idea of a good time is to use Windows Explorer to search for content in intro topics and attempt to figure out which one they want to reference.

For those of us without so much time on our hands, a content management system makes far more sense. A CMS provides both thoughtful and practical processes and tools that 1) help guide you during the import process and understand the shape of your data and 2) inform you of effective ways to get your data into a content management system.

The key to taming the file system, or what I lovingly refer to as the wild, wild, west, is through a mature import process that leverages the best tools the industry has to offer.

For example, maybe the DITA content you have created on the file system is very close to being “done,” and with just a few minor changes, you would be ready to publish. The import process and tools you adopt need to inform you of the readiness of your content so that you can make an informed decision. In this case, you might just elect to go back to the data, make the minor changes, and import a complete publication. If your process and tools don’t account for analysis, then you have no way of knowing just how close or how far away your DITA content is from being publishable.

Another example involves content duplication. Let’s face it; because it is so easy to copy things on the file system, it is likely, as I have seen, that your folks have already created several publications by copying maps and in some cases even all references.

Wouldn’t it be smarter to import the set of topics being referenced and then import the maps that refer to those topics? This sequence is critical if you really want to take advantage of powerful reuse capabilities and leverage the content you have created. The import process you adopt and the tools you employ need to help you manage your content so that you can take full advantage of your data and really start to push content reuse and that ever popular ROI. Do you really want 300 topics called “intro”? Probably not.

Without a sound process and industry leading tools, how would you even know if content was being copied? No one logs onto a file system. Is the plan just to hunt around the file system and put eyeballs on the data? Maybe you are using a spreadsheet to help, as many people do. But spreadsheets can become a management nightmare in and of themselves!

Let’s say you have really bought into DITA and have already started creating the required publications using the file system. You start by creating your publication outline—the DITA map—and then start to fill in the topics and tasks. You get the graphics group working on images for the publication, and life is good.

Of course, while this is happening, you and your team start looking at content management systems because you know that you will want to manage the content in a more structured environment, translate this content, and yes, even publish it. And while you’re at it, why not do it all at the push of a button.

While a sound import process can help you get from the file system to a content management system, let’s not forget about meeting delivery schedules. No one ever seems to forget about what you need to deliver, especially your manager. You still have to meet your delivery deadlines while you transition from file to content management system.

You finally have a content management system, your map is shaping up nicely, half of your topics are done, the other half are still being worked on, and about 100 images (that the topics will need) are being worked on in the graphics group.

How does your import process and tools help bridge this gap? Oh, what to do, what to do…?

“Wait until you are finished with everything to load the content?” No, not at all—that would be a waste of a very good content management system.

“Just put the topics that are done in?” No—you still need to manage, translate, publish, and proof your publications (maps) even if they are not 100 percent complete.

“Stop the presses (literally), give everyone the week off, and get all the information into the content management system in its current state?” Definitely not that!

What you need is an import process and a set of tools that will let you import your publications and data in their current form and let work continue in real time. You will need to know that a bunch of required content is not present. In this example, you may be missing half of the topics and all of the images. Your process and tools will need to guide you so that you know where to create place holders (just like a sticky note on a publication that says “place my really good topic.xml here”). You will want these place holders so that you can start the proofing and translation process in parallel with the continued creation of content. You will want to make sure that you have an easy way to find and identify these “sticky notes” so that you can continually monitor the progress of your publication. And your process and tools must allow you to come back tomorrow or the next day and replace the sticky notes with real content which you can then review, proof, and translate.

You have successfully moved from the chaos of the file system to the orderliness of content management, and with the right process and tools you were able to do it while still meeting those delivery schedules—whew!

You have taken a very important step by realizing that structured content and the DITA content model are the way to gain control of your content so that you can really ratchet up the ROI. When combined with a content management system, you quickly see that you are producing better quality publications, you are doing it faster because more of the process becomes automated, and your management overhead is greatly reduced, directly benefiting your bottom line.

This is all wonderful, but let’s not forget the legacy content that you will probably want to manage during or even after you transition to DITA. To date, I have not seen one customer take all of their content from its legacy form and move it to DITA. All have picked a point in time and said, from this point on, these publications will be in DITA, and legacy data will remain as is.

However, whether your legacy content is in FrameMaker, Word, or in another XML schema, you might want to consider the benefits that a content management system brings to this content. A content management system generally includes automated workflow, versioning, and a secure environment. And if your content management system can manage your legacy content and your DITA content in the same repository, you get an added bang for your buck.

If you think through your import process and pick the right tools, you can rest easy because you know your content is in process. You are going to be able to say in just a few short weeks…

“You mean all I have to do is push this button, and I get my publication in PDF, HTML, Help, and Word and in 31 different languages? Aruba here I come.” CIDMIconNewsletter

©2006 Jon Chomitz Photography 3 Prescott Street, Somerville, MA 02143 617.625.6789

Mark LeBlanc


Mark LeBlanc has been guiding the design and development of leading edge technology for mission-critical applications since 1998. He has driven the evolution of the company’s core products, including the industry’s first Web-services-enabled publishing platform, migration to an open architecture, and XML-based content management technology. Experienced in engineering process modernization, he has established a world-class engineering team, consistent business processes and customer-driven R&D. Mr. LeBlanc’s responsibilities include overall product strategy, quality assurance testing, research and development, and engineering support. He has extensive experience in data warehousing, information delivery and open systems, having designed and developed COLD (Computer Output to Laser Disc) systems for Filemark and Data General, prior to joining XyEnterprise.