Skip to main content
November 12, 2018

Managing DITA projects: Five keys to success

Executive summary

You just completed a content strategy analysis. Your analysis concludes that the Darwin Information Typing Architecture (DITA) XML standard will provide a great framework for your company’s content. You are ready to set up a DITA system, but where do you start?

Implementing DITA is not just a matter of picking tools. In fact, software selection is usually the easiest part of a DITA project. This white paper describes best practices for five critical facets of a DITA project.

Ensuring clear communication

Managing change is critical for your DITA project’s success. Clear communication through all phases of the project is the essential component for successful change management.

Good content addresses its audience at the right level. Take the same approach when communicating with the different groups affected by a DITA implementation. Talk to project stakeholders about their concerns and requirements in language they understand.

For example, occasional content contributors (such as product engineers) need reassurance that they can contribute content quickly and easily, perhaps through a browser-based interface. Full-time content contributors, however, want an XML authoring tool with many features. The IT department does not want to support tools that have the same features, so they need to understand the business reasons for providing two authoring experiences. Executives who approve projects will care little about authoring solutions. They are much more interested in finishing the project within budget and reaping the benefits of the DITA system as soon as possible.

To ensure success, align your DITA project with other strategic projects and how they are managed in your organization. Have regular status meetings during implementation, and communicate with stakeholders through the channels they prefer. (If an executive requests a presentation on project status, sending just an email is not a good idea.)

Even with an excellent DITA system in place, the communication must continue as you roll out the environment and train users. Targeted training should educate casual users, power users, and administrators in separate sessions.

Encourage new users to provide feedback on trouble spots so that you can make needed adjustments. User feedback will also help improve training for the next group of employees.

Content modeling

Even though you have chosen the DITA standard as your XML model, you still need to work through the process of content modeling: determining how the organization and classification of your company’s information will be represented within DITA.

You can start by creating an inventory of styles for your current authoring tool. Then, list out the DITA equivalents for those styles. Seeing how existing information works in DITA is a good way to learn the DITA structures.

However, do not focus exclusively on how you created content in the past. You may not have followed DITA best practices in your old content (for example, creating small chunks of modular content that you can reuse and share). To develop high-quality DITA content, you may need to change or completely rewrite content.

You also need to figure out how to track metadata—data about your data. In DITA, you can use metadata in many ways, including:

  • Filtering what content is included or excluded in a publication (conditional text)
  • Refining searches
  • Including processing instructions for delivery formats (for example, the IDs for context-sensitive help)

There are other content modeling considerations. Do you need additional structures and metadata to fully support your content requirements? A selling point of DITA is the ability to modify the default structure without deviating from the standard. You create new structures based on existing ones through the process of specialization.1

DITA also offers several mechanisms for content reuse. During the content modeling process, develop a formal content reuse strategy.

Repository icon labeled "Repository" filled with water, (ombre of blue lines). Arrows come out from the repository to three different cup shapes with different colors.

Evaluating tools

As you sift through cheery marketing claims for DITA tools, go back to your initial content strategy analysis. You chose DITA to meet specific business requirements. While evaluating software, stay focused on those requirements. Your shopping list may include a component content management system, authoring tools, review tools, a translation management system, and more.

Avoid using your current tools’ capabilities as benchmarks for new tools, particularly when moving from desktop publishing to XML. Desktop publishing and XML environments have different authoring experiences, so direct feature-to-feature tool comparisons are not useful. For example, the ease with which authors insert page and line breaks in their desktop publishing program is irrelevant—in a DITA environment, formatting is not applied during the authoring process. Instead, an automated transformation process formats the content later.

Because of different stakeholder requirements, you may need multiple tools for a single task, particularly for authoring. Part-time and full-time content contributors require different levels of complexity in authoring tool features, so it may be more efficient to provide multiple authoring experiences in your DITA workflow.

Create a spreadsheet with weighted requirements so that important tool features get priority during evaluation. You can also develop short narratives that explain specific use cases. Ask each vendor to demonstrate how their tool supports those use cases.

Evaluate vendor claims carefully. If you have identified specific DITA constructs as critical to your workflow (reuse methods, for example), ensure that vendors’ demonstrations show how their tools support those DITA features.

Independent consultants such as Scriptorium are experienced in developing requirements and evaluating vendors. An investment in a consultant can result in better decisions.

Delivering content

You can transform your DITA XML content into web pages, PDF files, and other formats through the DITA Open Toolkit.2 The Open Toolkit is not the only way to publish your DITA content. Other DITA tools provide additional publishing mechanisms.

Repository icon with the label "Authoring" has an dotted line arrow that branches into three lines, each of which are labeled "rendering." Each line points to a different icon of different cup shapes in different shades of blue.

The default formatting from the Open Toolkit is very unattractive, but you can modify the look and feel to match your company’s corporate style. The source content for this white paper is in DITA, and Scriptorium customized DITA Open Toolkit transformations for both the web and PDF versions of the paper.

The good news is that once you have the customized transforms in place, it’s a quick, pushbutton process to create the delivery formats from the DITA source files. You can also set up automated batch processing so updated output is generated at regular intervals.

The toolkit’s output capabilities are extensible. For example, Scriptorium has developed transformations for EPUB ebooks, Android applications, InDesign-compatible XML, and much more. Consider getting help from an expert like Scriptorium if your team does not have the necessary programming experience.

Considering conversion

Before you think about converting your existing content to DITA XML, research DITA best practices. The DITA specification itself contains limited best-practice guidelines.3 Supplement your research in the specification with a reference such as The DITA Style Guide that offers advice on how to implement the DITA model.4

If your content is not tagged consistently, it is more difficult to automate conversion through scripts—whether you have an internal resource for the scripting or you work with a conversion vendor. Also, if your content is not easily broken into chunks that are the equivalent of DITA topics, you may need to rewrite it.

Even if you are not going to convert existing information to DITA, you still need content to test your DITA model and the delivery transforms. Create a collection of DITA files that represents the types of content you create and distribute. Collect enough content to ensure you are thoroughly testing your processes and transformations.

Be prepared to address complications during your conversion project (for example, poor tagging or odd layout in a subset of files). Leave ample time in your schedule to address those issues.

Conclusion

A DITA project has many moving parts: content modeling, tool evaluation, customizing delivery options, conversion, and more. Let your business requirements guide how you address these technical aspects. Consider getting help from an experienced consultant such as Scriptorium to ensure you choose and implement the right technology.

Always look beyond the technical issues—work closely with all project stakeholders to maintain the constant communication that is key to your success with DITA.

Have questions about how to implement DITA? Contact us.


References

  1. White paper on specialization: scriptorium.com/2017/10/dita-specialization-extensibility-and-standards-compliance/
  2. Download the DITA Open Toolkit for free at www.dita-ot.org.
  3. DITA specification: docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-inclusive.html
  4. You can read The DITA Style Guide for free online.