Reusing your DITA Solution (or How to Get Money to Buy One)

Home/Publications/Best Practices Newsletter/2010 – Best Practices Newsletter/Reusing your DITA Solution (or How to Get Money to Buy One)

CIDM

October 2010


Reusing your DITA Solution (or How to Get Money to Buy One)


CIDMIconNewsletterLaurens van den Oever, SDL Structured Authoring Solutions

To get the most out of DITA, a Component Content Management System (CCMS) is a must have. But a CCMS can be a big investment, and even though the ability to reuse content components can dramatically increase efficiency, it may be difficult to justify such a purchase for your team.

It would certainly help if the CCMS would be used by more people in your business. The investment would be beneficial for a larger part of your organization and, as a result, would make it easier to get the required budget from your management.

Who to Share Your DITA With?

Even though DITA is often used for technical documentation, it was originally designed to be adaptable to the specific needs of an organization. Accordingly, you can adapt DITA to virtually any kind of document and share the benefits of the CCMS with the authors of those documents.

Engineering

The first place to look for potential DITA users is the engineering department. The products built there are the products documented. If the engineers can deliver their raw material in DITA, the documentation process can start very efficiently. In return, the engineers can work in a structure that can guide them while writing, just as software engineers have auto-completion tools. The same applies to project documentation like requirements and specifications.

Support

On the other side of the product lifecycle is the support team. They may want to use their knowledge of the products on the market to extend the existing DITA-based documentation. Issue descriptions and knowledge-base articles are documents with a fixed structure. Being able to publish them to print, web, and on-site mobile device is very valuable. DITA markup will also facilitate customer search into specific parts of those documents.

Sales

When they are writing offers or proposals, the sales team is often reinventing the wheel. Each team member typically has his or her own set of past offers to copy from, all with a company description, case studies, offered capabilities, and terms. If the company changes, like most do on a daily basis, each member has to update his or her set offers. With DITA, the sales team could reuse content from a centralized set of content components, like case studies, choose what is relevant, and improve them if needed. When they close the deal, the same applies to Statements of Work.

Marketing

To efficiently market your products, it is vital to quickly react to changing market conditions with consistent campaigns over multiple channels. With DITA, you can create one repository from which you can feed each channel. A 140-character tweet may be good content for a call-out box in a brochure. If you’re marketing globally, being able to reuse previously translated content can drastically reduce costs and time to market. Having separate teams working shared brand and campaign content also improves efficiency.

As you can see, in almost every aspect of the business, people are creating documents that can be structured. There are many more examples where adding structure to documents can improve business efficiency. In fact, if you are creating many documents of a particular type, like policies, contracts, or press releases, it can be worthwhile to consider using DITA.

How to Make DITA Friendly for Your Colleagues

We’ve established whom you could share your DITA solution with. The next and greatest challenge is to make the solution fit the new type of authors. Unlike trained technical writers, these authors don’t know XML and may not have any Content Management System experience. Fortunately, you can configure these systems for our new group of authors.

Getting to the content

The first task is to hide most of the content repository. The authors only need to have access to a small number of documents. Because sharing content between lines of business is unlikely, at least in the first iteration, you can give each group its own dedicated part of the repository. The interface can be drastically simplified, removing complex searches and other management tasks, leaving only a familiar file system-like interface. Depending on requirements, CCMS configurability, and budget, you can decide to create a dedicated interface for specific lines of business.

No more documents

With the introduction of DITA, the notion of documents is gone. Or is it? Topic-based authoring is one of the core features of DITA, but the new authors may not need to create multiple publications (ditamaps) reusing a single topic. Even without separate topics, reuse of content is still possible using conref. At least initially you can consider hiding the notion of topics. The simple solution is using nested topics, and a more advanced solution would be hiding the ditamap infrastructure everywhere, including in the authoring interface.

WYSIWYG

A What You See Is What You Get (WYSIWYG) interface is mandatory for the new authors. Unfamiliar with XML, they need to see the content they write in a familiar context. The authoring interface should hide as much of the structure as possible and certainly not expose the tags. That also means that the authoring tool needs to automate all actions that require knowledge of the structure. An example is the insert position. If the author can’t see the tags, the authoring tool should insert new elements and attributes in the valid location even if the cursor is only roughly in the right location.

Another challenge is the multiple output formats DITA offers. If your marketing team plans to publish the same content in print, on the website, and on slides in a webinar, there is not one WYSIWYG view. In that case you can offer multiple views and have the authors use the richest view, or you can create a custom author view representing most of the target platforms. And such a custom author view can be enriched with tools to aid the author, like context-sensitive insert buttons.

You should be aware of the level of control the author may have. If the author can’t control the conversion process to slides, it makes no sense to offer that as an authoring view.

Familiar Knowledge Domain

Out of the box, DITA was designed for technical documentation. Those structures probably don’t match the logical relations and naming familiar to the new group of authors. A good starting point for the new types of documents can be one of the new specializations like DITA Learning and Training. You can also create specific specializations or use constraints to match the created structure as closely as possible to the content the authors are familiar with.

As an alternative to specialization, which can be complex and expensive to develop, or as an addition to constraints, you can use aliasing to introduce familiar jargon. Aliasing is a feature of an authoring tool that allows you to substitute element and attribute names with more familiar, friendly, and possibly localized names.

In general, it is important to offer the authors only choices that are relevant to their knowledge domain. So, if the order of elements is fixed, don’t offer the option to reorder. If structure is mandatory, make sure it is automatically created. If information or metadata are available from other sources or databases, use tight integration to pre-populate new documents.

When in doubt, remove elements and structure choices; it is always easier to go from a strict, well-defined structure to a more relaxed structure with more elements and options. The reverse will require a full content migration. Consider the standard <section> element in DITA. Out-of-the-box it will allow both:

<section>

<title>New section</title>

Section text

</section>

And:

<section>

<title>New section</title>

<p>Section text</p>

</section>

This gives the author a choice to either put the text in a <p> element or directly in the <section>. Because very few authors will understand the difference between these examples, they should not be given this choice. Allowing text in the <section> element will also allow text before the <title>. That is a choice we don’t want to give our authors, so we prefer the second structure where we can control the position of the <title> relative to the rest of the section content. If we need to support the first structure in the future, we can revoke the constraint placed on the XML Schema/DTD. This will revert the editing environment back to the base DTD configuration. All existing topics will still be valid. However if we had chosen the first structure and decided to make the XML Schema/DTD more strict to only support the second structure, we would have to convert all topics with text directly in the <section> element as they will no longer be valid. You will also have to figure out how to handle exceptions like text before the <title> element. If you have the choice, try to limit the number of variations where possible since fewer variations will make it easier for you to add structural options in the future.

Authoring Structured Content

Perhaps the biggest challenge is authoring valid structured content. Selecting the right authoring tool is key to getting the solution accepted by the new authors. Since these authors don’t know XML and typically have no notion of a hierarchy in a document, they can’t be expected to fix XML Schema/DTD validation errors. Therefore, they need an authoring environment that prevents all possible validation problems.

There are a few approaches to achieve that ease of use. You can simplify the structure so that the authors can’t go wrong at the risk that you are left with insufficient structure to achieve all your envisioned benefits. Or you can have a trained author fix any problems with the content, resulting in added overhead which you planned to reduce in the first place. Or, you can use an XML editor designed to keep the document valid at all times and prevent all actions that make the document invalid.

With the document valid, you need to make sure the authors use the right structure for each bit of information. It is important to make all relevant choices easy to find. Some editors can show in-context insert buttons. Some automatically create the relevant next structure when the author presses enter or tab based on what they would expect using a standard word processor.

In some cases, you may be able to use current, consistent styling. If a team uses italics as a convention for keyword, you can link the button to insert italics to the keyword element. To prevent the authors from abusing the keyword element to emphasize text, you can bring some of the behavior of the keyword element to the authoring interface. Keyword could mean that you show a list of currently marked keywords in the document. Then, if an author tries to mark something incorrectly as a keyword, it would immediately stand out. An immediate benefit of this approach is the ability to copy and paste legacy content. If you can link the italics button to keyword, you can also have the authoring tool convert italics to keyword elements.

Reuse

Content reuse is a core feature of DITA and a compelling reason to use it. If you have created content before, why would you spend time and money to create it again? But content reuse is complex; you have to give it some thought before offering it to inexperienced authors.

The first challenge is offering reuse options to authors who will most likely not search for reusable content. In this case, the domain specific structure can help. If you are creating specifically structured documents like offers, the structure can define a section for case studies and a section for business capabilities. Creating a new case study section can then trigger a search for all existing case studies and allow the author to point and click to reuse the relevant content. Metadata associated with the author in the underlying CCMS can be used to further limit the scope of these searches.

Another challenge with reuse is the danger of changing a content component that is in use elsewhere. A good CCMS can show you where content is used, but proper management and understanding what happens if you change a reused component can be difficult. For these authors, you may want to block changes to content that has been reused. If the content must be changed anyway, it is probably better to offer an easy way to make a copy. An advanced solution can notify the authors of content that reuses the changed component so they can decide if they want to accept the change or not.

On the other side of reuse is the concept of writing content to be reused: topic-based authoring. Because these authors probably will not accept writing separate content components, the authoring view should show all topics in context. Topic nesting has the risk that technically separate content components are textually interlinked. Think of paragraphs starting with “As mentioned above” or “Another example is”. Unfortunately this can only be caught with a review from an experienced author. But if you choose the structure wisely, you may be able to coax the authors to write components. When reusing case studies in the sales team, creating a well-defined structure for a case study will force the authors to think about small units of information like company descriptions and business benefits.

Conclusion

If you introduce DITA with a familiar interface and jargon, stick with a strict and relevant structure, and use the right authoring tool for non-technical authors, then you can share your DITA solution with other lines of business. Sharing content across the enterprise helps you deliver a more convincing business case to your management and improves the success of the implementation of DITA in your organization. CIDMIconNewsletter

Laurens van den OeverLaurens van den Oever

SDL Structured Authoring Solutions

lvdoever@sdl.com

Laurens van den Oever is SDL Director of Structured Authoring Solutions. Before that Laurens was CEO and Co-Founder of Xopus BV. Laurens has over a decade of experience with internet technology and structured content management. With a firm understanding of underlying web technology and the intricacies of XML authoring he lead the success of Xopus resulting in the acquisition by SDL in 2010. Being Dutch, he likes to cover some distance on his bicycle to stay in shape.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close