By Scott Abel, The Content Wrangler
Over the years, I’ve been quoted as saying, “You can’t do that with Microsoft Word and SharePoint”. More specifically, I usually said something like “If you want to move to the Darwin Information Typing Architecture (DITA), then Microsoft Word and SharePoint are absolutely the wrong tools for the job.” But, that’s not true any more. With a little help from DITA Exchange, ”Yes, you can move to DITA using Microsoft Word and SharePoint.”
This article seeks to explain, at a very high level, with minimal mumbo jumbo, why I believe it’s possible — and even attractive — to consider using the software you probably already have in place in your organization today to make the move to DITA and component content management as painless as possible.
As an enterprise content strategist, I’ve seen just about every content challenge imaginable. While the problems each of my clients experience are often perceived as unique, most of the time, except in rare situations, they are anything but. In fact, most organizations are struggling to solve the same exact problem as every other content-heavy organization on the planet: Delivering the right information, to the right people, at the right time, in the right format and language, on the device of their choice.
Solving this critical challenge in a way that benefits your entire organization is the goal. It involves conjuring up a ‘perfect storm’ of people, processes, and change. Add to the formula the right mix of new methods, roles, responsibilities, metrics, content standards, training — and, of course, technology — and you’ve got a recipe for success.
Most publishing challenges can be solved by changing the way an organization views content and how it should be created. Central to this shift in thinking is the acknowledgment that in order to get content to work for the organization, it needs to be created, managed and delivered in the most efficient and effective manner possible.
More often than not, this means creating structured XML content components, separating them from their formatting information, storing them in a content repository, streamlining their production lifecycle with the help of workflow, ensuring their consistency with the help of content standards, and guiding their creation using software tools that understand the rules, and that assist — not hinder — those who create them.
Enter DITA Exchange
DITA Exchange is a suite of software tools designed specifically to enable Microsoft Office and Microsoft SharePoint users to create, manage and deliver DITA content. It includes modules that aid in the creation of topic-based DITA content from within Microsoft Word, making it possible to efficiently manage the production of topics in SharePoint, while also enabling non-experts to easily create DITA content and publish DITA maps (collections of topics) to a variety of outputs.
Plain and simple. It prevents those who do not need to understand DITA, XML, and the DITA Open Tool Kit (yuck!) from the pains associated with moving to DITA by allowing them to work within the confines of software products with which they are already familiar. Instead of struggling to learn a new XML authoring tool, while simultaneously learning a new approach to creating and managing content, DITA Exchange empowers content creators of all skill levels to make the jump to DITA without specialized knowledge and in-depth software training.
What Is Included In DITA Exchange?
At a high level, DITA Exchange is comprised of the following modules:
- DITA Exchange Foundation – empowers Microsoft SharePoint to recognize, understand, locate, and manipulate DITA content. It turns a ‘SharePoint library’ into a ‘content component library’ — a repository for the storage of DITA topics, DITA maps, and associated metadata. It enables SharePoint to understand the content rules spelled out in the DITA schema, as well as the relationships between topics and topic maps. Among its many useful features, it provides a “where reused” function designed to help content contributors and managers know where reusable topics have been repurposed.
- DITA Exchange Transformation Services – enables the exchange of DITA content between Microsoft Office format (OpenXML) and DITA. It makes it possible for DITA content to be rendered (output) using Microsoft Office templates, avoiding the need to interact with the DITA Open Tool Kit and stylesheets. (Yay!) It also supports more efficient management of DITA content throughout its lifecycle by allowing those involved in the content lifecycle to create, edit, revise, and approve DITA content using Microsoft Word documents, without the need for additional plug-ins or helper applications.
- DITA Exchange Desktop – contains a Word plug-in that allows you to create, edit and tag DITA topics, turning Microsoft Word into a full-featured DITA authoring tool capable of outputting DITA content to a variety of formats using Word templates. It contains a separate, optional plug-in — Topic Picker — that allows users to find and reuse topics on-the-fly, quickly and easily.
How Does DITA Exchange Work?
At a very basic level, this is how DITA Exchange works. Software components are installed that enable Microsoft Office and Microsoft SharePoint to provide content contributors with the ability to create structured, XML content (DITA topics) from within the ubiquitous Microsoft Word environment. Contributors use Word in much the same way they do currently, but they are guided to create valid DITA content by the user interface and some helpful instructional text.
Once the content is created, DITA Exchange saves it into SharePoint Server, which has been configured to act as a content component (topic) library from which content can be managed at a granular level. When it comes time to publish DITA content into specific deliverables (user manuals, online help, website content) users select the DITA topics desired, organize the content into a topic map, and publish the content — all from within Microsoft Word — to a variety of output formats (PDF, XML, HTML, several types of online help, Microsoft Word, etc.).
Pretty easy, huh? Not one reason to interact with the DITA Open Tool Kit, Ant, or XSLT. So far, so good.
With DITA Exchange, authors can save DITA topics into the SharePoint topic library from within Microsoft Word. The library provides authors with direct access to previously created, reusable DITA topics, as well as other content assets, including multimedia files, images, and unstructured legacy content. It also includes standard content management features such as check-in/check-out, version control, change control, and an extremely useful “preview” feature that allows authors to see the final product before it’s published.
DITA Exchange makes Microsoft Word users think they are creating Word documents, when in fact they are creating content components that will later be compiled into the output deliverable desired. For non-expert XML authors, the authoring process is more like completing a form than authoring an XML file. The rules (structure, content, etc.) are enforced in Microsoft Word and helpful hints are within a template can be provided along the way to guide authors in the creation of valid DITA content.
Advanced, XML-savvy authors can, with the click of a mouse, enter an XML authoring view in which all code is exposed. DITA Exchange Word Editor allows these authors to switch between the WYSIWYG and XML views, when desired. Oh, the XML-savvy authors are also free to use their XML editor-of-choice with the DITA Exchange CCMS.
Editing documents is also easy and quick. DITA Exchange includes an “edit” button in the documents generated from it that allow editors to open a document and edit the individual topics contained within it. When the editor updates a file, the changes are saved back to the topic library, so that all documents that include that topic are updated as well.
Once it’s time for publishing, DITA Exchange makes it easy to create a variety of outputs. Gone are the days of interacting with the less-than-user-friendly DITA Open Tool Kit. Instead, the DITA Exchange publishing engine gathers and transforms the DITA content into DITA topics — Microsoft Office documents (usually Word, but PowerPoint is possible too) PDF, HTML or any combined XML format such as IDML (for Adobe InDesign). The output is, assembled in accordance with the DITA map selected, and formatted according to the output format desired a Microsoft Word template. For instance, to create HTML Help, the author would create a DITA map containing all of the needed content, click “convert document”, point to the DITA Exchange publishing engine, select an output template (in this case, HTML Help) and then click “publish”. Changes desired in the output formatting can easily be made to the Microsoft Word template. The next time the template is used by the publishing engine the changes made will be reflected in the content output.
What Are Some Of The Problems DITA Exchange Solves?
Let’s take a look at some of the common challenges faced by organizations who are making a move to DITA and how DITA Exchange can help address them.
Who Should You Consider DITA Exchange?
Adopting DITA Exchange makes a lot of sense for many types of organizations. It’s not really about size, although DITA Exchange certainly makes sense for large, multi-national firms in the manufacturing, publishing, transportation, telecommunications, government, defense, e-Commerce, entertainment, high technology, and healthcare sectors. But it is also an attractive option for those in regulated industries like life sciences, where pharmaceutical and medical device firms have been struggling to make the move to XML for years, with varying degrees of success.
For small-to-medium sized businesses that often lack the resources to make the move to DITA without considerable pain and expense, DITA Exchange presents a practical alternative. The primary components — Microsoft Office and Microsoft SharePoint — are widely deployed around the globe and probably already in use by employees of these firms. There’s a significant talent pool (programmers/developers) with experience in .NET (the framework upon which DITA Exchange is built) who can be called upon to ensure DITA Exchange implementations run smoothly. They can also help extend the solution in the future to do things you don’t anticipate needing today. And, little specialized technical knowledge is required to make changes to templates once the system is up and running, saving big bucks on consulting fees paid to stylesheet designers and XSLT jockeys.
The Benefits of DITA Exchange
There are many benefits to adopting DITA Exchange and they vary depending upon where you are on the DITA adoption lifecycle. The most common — and biggest value — benefits as I see them are:
Authors don’t need to learn DITA (but they will need to learn to write for reuse, master minimalism, and learn the ins and outs of topic-based authoring)
- Authors won’t need significant software training (but they will need to learn how their roles and responsibilities have changed and how using the software in specific ways will help them accomplish their duties)
- Publishing consulting fees will be drastically reduced (you’ll not need consultants to configure your content publishing engine, jimmy-rig the DITA Open Tool Kit, and build stylesheets for you; but you will need consultants to help you analyze and model your content, assist in the re-engineering of your content lifecycle, redefine roles and responsibilities, manage change, design templates, and to ensure that your project is implemented correctly)
- Enables XML gurus and inexperienced contributors to collaborate across the enterprise (contributors of all experience levels can create valid DITA content working together, without any specialized knowledge or training)
- Facilitates content reuse across the enterprise (exposes content to others in the organization; allows them to reuse and repurpose that content into new information products and output deliverables)
- Eliminates need to purchase additional XML authoring and component content management systems (saving you money)
- Minimizes change management issues (you’ll still have plenty of changes to teach everyone about, but they won’t be focused on learning XML, mastering both a new XML authoring system and a new component content management system)
Concluding Thoughts
Despite what many people believe, it’s not technology that’s the biggest obstacle to success when moving to DITA. The biggest problem faced by those who hope to move away from old school content creation methods are the humans we inflict change upon. Most people don’t like change. It introduces anxiety and unnecessary fear. So, the best thing we can do is make the big changes as easy as possible for those we expect to change.
I didn’t use to think this way. In my earlier years, I thought that if a better way of doing things was discovered, company management should tell their employees they are going to change, and that they expect them to make it happen. Unfortunately, humans don’t all work the same way. Nor do they learn in the same manner. Some are excited by change, some find it tolerable, but for a vast majority of people, change is often undesirable.
Because XML is extensible, DITA can be expanded or enhanced to provide new capabilities not envisioned in the original specification without having to make major changes to the existing infrastructure.
I’m excited about DITA Exchange not because it’s a magical tool set, but because it makes it possible — and practical — for organizations of all sizes that currently utilize Microsoft Word and Microsoft SharePoint to jump on the DITA bandwagon with minimal pain and expense. I believe it’s critical to get large numbers of companies using the DITA standard, extending it to meet their business needs, and making it more attractive for others to follow suit in order for us to gain widespread adoption of the standard. DITA Exchange is well-positioned to help many organizations move away from creating unstructured documents and toward creating semantically-rich, structured XML content that can be delivered to those who need it in increasingly innovative ways.
