A Business Case for Authoring Content in the Darwin Information Typing Architecture

Home/Publications/Best Practices Newsletter/2005 – Best Practices Newsletter/A Business Case for Authoring Content in the Darwin Information Typing Architecture

CIDM

December 2005


A Business Case for Authoring Content in the Darwin Information Typing Architecture


CIDMIconNewsletter Visnja Beg, IBM Canada Ltd.; Amber Swope, IBM Corporation

Major changes to information development practices, such as moving to a topic-based, XML architecture, require business-case justification. This article describes a business case for authoring content in DITA, including how to save money, maximize limited resources, and improve content quality.

What is DITA?

The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating “information-typed” modules at a topic level and for delivering content in formats such as online help, softcopy and hardcopy documents, and product support portals on the web.

The Organization for the Advancement of Structured Information Standards (OASIS) formally accepted the DITA specification as an open-source standard. This means that the architecture has broad participation and support in the information development industry and no single company controls its development.

Topic-based architecture
The foundation of a topic-based architecture is a unit of information called a topic. In DITA, topics are governed by types, which provide structure for the topic content. The structure defines the valid elements for each topic type and provides consistency between topics of the same type.

Information types identify which information appears in a topic. The three base DITA topic types are task, concept, and reference. The topic type determines the structure of the topic and controls the content through supported elements for each topic type. For example, you can add steps only to a task topic.

Customization through transforms
Because you separate content from format with XML, you can easily change the presentation of information by updating or creating transforms. This means that you do not have to alter the source files to provide the same information in multiple formats with different layouts and styles. Instead, a transform can generate each format from the same source files.

For example, if you provide application programming interface (API) documentation as MAN pages and Javadoc, you use the same source, but generate each deliverable by using the appropriate transform.

Extensibility through specialization
With DITA, you are not limited to the base set of information types that the DITA specification supports. You can extend or customize your DITA implementation with specializations that you can use to define new kinds of information (new structural types or new domains of information), while reusing the existing design and code. This means that if you need to author a specific type of content with a consistent structure, you can write a specialization based upon the currently defined DITA topic types.

For example, if you want to consistently author API documentation, instead of using the reference topic type, which might contain elements that information developers do not need for API documentation, you can create an API reference specialization that contains only the elements that are appropriate for API information.

As more people adopt DITA and publicly provide their specializations through OASIS, the more you can leverage existing specializations and receive support from an established community.

Linking support
Users find their way through online information using navigation links, such as the table of contents, as well as nonhierarchical links between topics. In addition to supporting hand-coded links, DITA uses map files to specify and automatically generate links between topics.

Saving Money

In the current fiscal climate, you must justify expenditures and reduce costs wherever possible. One strategy to reduce costs is to streamline the content authoring and production processes. Because DITA uses a consistent set of information types and structured topics, you can guarantee structural consistency across topics in an information set. This consistency enables you to automate and streamline several processes to optimize topic processing, such as building and testing topics, and packaging them for translation. For example, if you translate similar or duplicate information in different formats, such as in an online help system and a printed manual, and you have not single-sourced the content, you pay to translate the same information twice. However, if you translate the DITA source and then reuse the content for each delivery format, you only pay to translate the content once.

Another way to save money is to perform work only once. As an XML authoring solution, DITA separates format from content. This means that you can easily update the format without incurring the cost of manually updating the content source. You simply update the element information in the cascading style sheet and regenerate the content to update all instances of the element. For example, if the format of the word “Note” in a notice changes from bold to bold and italic, you can update the definition of the note element and regenerate the topics to apply the current style.

If you work with original equipment manufacturers (OEMs) and need to reuse their content, you can save money by using the same architecture. Because DITA is an open-source standard architecture, there are no proprietary restrictions on using it and you can easily coordinate DITA implementations, including customizations with transforms. In addition, if you use DITA, but have different formatting standards, you can still easily share the content source and inexpensively generate the information to meet your company styles.

Maximizing Resources

Today, many businesses face the challenge of doing more work with fewer resources. In information development, one strategy to maximize resources is to reuse content for multiple deliverables. When information developers reuse content, they avoid duplicating information and work by using existing content. To do this successfully, teams must use consistent, structured information.

DITA supports content reuse with well-defined topic types and DITA maps. For example, if an information developer writes a task about setting properties and needs to provide conceptual information about them, he writes a DITA concept topic that defines properties. If another information developer needs to provide the same information, she does not have to write the information again; instead, she can reuse the entire concept topic by including it in another DITA map.

In addition to supporting full topic reuse, DITA also supports single-sourcing content at the XML element level. This means that information developers can reuse individual pieces of information in multiple places. If the original source changes, all referenced instances of the information are updated when you regenerate the referenced content. To continue the previous example, if the second information developer needs only a specific portion of content from the original concept topic, she can use DITA to reuse specific elements of information, such as a paragraph. If someone updates the source paragraph in the original concept topic, when she regenerates the project with the referenced paragraph, the reference updates match the source.

Another way to effectively use resources is to help information developers focus on writing content. Because DITA separates format from content, information developers do not have to remember the current formatting standards. They simply apply the appropriate XML element and the transform automatically applies the proper formatting. For example, information developers do not have to remember that the current standard for the word “Note” in a notice is bold. If they apply the correct element, the transform applies the bold style automatically to all note elements.

DITA enables information developers to focus on researching and writing content by taking the guess-work out of topic construction. Because each topic type has a valid structure that supports a specific set of elements, information developers simply insert the appropriate element and write the content. By having only the valid elements available for insertion at each point in a topic, information developers select the appropriate element from the list and do not spend time considering which element is valid for the topic type they are authoring.

Hand-coding and testing links between topics for online information is labor-intensive. DITA maps automatically generate many links, including the navigation hierarchy and links between topics. If an information developer changes the title of a topic, by default, the DITA map automatically updates the topic title for the link when you generate the files. This means that information developers do not spend time manually entering and maintaining links, including topic titles, and they no longer spend large amounts of time testing links. Instead, they create and maintain a DITA map, and the links are updated when the deliverable is generated.

Improving Quality

In information development, high quality means several things. First, information must be accurate. Because DITA enables information developers to focus on content, they have more time to ensure that the content is correct.

Second, information must have a consistent format and appear to have a single author. This seamlessness is a challenge for teams with multiple writers who contribute to the same deliverable. The well-defined structure of DITA encourages consistency of content regardless of which information developer creates it and promotes a homogenous look and feel.

Third, in online information, links must work. Users navigate online information by using links and if links are broken, so is the user experience. Because DITA maps automatically generate links, you can more easily provide intact navigation paths through your information.

Lastly, information must meet your customers’ needs. You can have accurate, consistently authored information with working links, but if the information is not what your users need, it is not high-quality information. To help you deliver the specific information that your customers need, DITA provides support for customizing and extending the architecture through specializations. You can reuse your accurate, useful information in tailored deliverables by using DITA maps to provide only the subset of content that each user needs and by generating the deliverables in the format they need.

Summary

If you want to save money and use resources more effectively while providing high-quality information to your customers, DITA might be your solution. As a customizable, extensible architecture, it can grow with your business to meet your changing needs without requiring costly changes. Because it is an open-source standard, you can contribute specializations and benefit from the specializations of other teams who face the same challenges. CIDMIconNewsletter

About the Author

Begswope

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