ClickHelp as a DITA Alternative

What Is DITA?

DITA is short for The Darwin Information Typing Architecture. It comprises the principles of specialization and inheritance that are much like the Darwinian theory. “Information typing” means the classification of information into topics, not “typing” as in keyboarding 🙂

“Architecture” is a hierarchy of elements or adaptable set of structures. It provides vertical headroom (new applications) and lateral extension (specialization into new types) for information.

“DITA is an XML standard for authoring, generating, and providing technical information.”

The idea of creating such a data model belongs to IBM, which needed more effective reuse of content in products’ documentation. So the technical publications department presented DITA in 2001 for internal use. In 2004 DITA was donated to the OASIS standards organization. The latest version was released in 2016, it’s called DITA V1.3 Errata 01.

DITA consists of a set of design principles that help to create and manage content separately from formatting. If you want to understand how it works, you must understand how DITA uses topics, maps, and output formats. You create your content in DITA topics, apply DITA maps to define which topics move into which deliverables, then handle those maps to DITA output formats to produce your final deliverables.

What Is a DITA Topic?

A topic is the basic content unit of DITA. It is understood separately and used in different contexts. A topic should be brief to distinguish a single subject or answer a single question; at the same time, it must make sense and be written as an independent item. It has a fixed structure, which helps topics be consistent even when written by different authors. DITA 1.0 and 1.1 provides three basic topic types:

• concept topics for overview and high-level explanatory information
• task topics for information about performing specific tasks
• reference topics for detailed information

DITA 1.2 includes additional topic types (specialized for learning plans, overviews, summaries, and assessments).

Confused already? Yes, it’s not so simple. And DITA introduces a lot of items that should be well-understood for the efficient application of this approach in action. Let’s continue to introspect in other elements to understand what issues are addressed with the help of DITA for the technical documentation creation process.

What Is a DITA Map?

A map is a list of indications to a set of some particular topics. It determines topics to incorporate into the deliverables. The map also establishes the order and hierarchy of the topics and ensures browsing, such as TOC and cross-topic links in the final deliverable. Maps can be created at any time, even before the topics’ development. Additionally, maps can create multiple deliverables from a single set of topics. Typically, more than half of topics are used in multiple maps. You should remember not to create a dependency between topics, they should be context-neutral. Because in case of some changes in such dependent topics, your reader may go on the wrong path. You can also use a single map for multiple deliverables. Maps can point not only to topics but also to other maps. Using maps gives you flexibility but can significantly complicate the understanding of the process. In cases you need only two or three output variants with the set of topics that are 90% concurrent, the creation of separate maps for each output can bring in extra overhead.

What Is an Output Format in DITA?

Output formats allow producing various deliverables suitable for different purposes (posting to the web, printing, etc.) from a content. By default, the DITA-OT provides output formats for:

• XHTML
• Compressed HTML Help (.chm)
• PDF
• Eclipse Help
• JavaHelp
• Rich Text Format (RTF)
• etc.

Also, you can develop your own output format. It can be modified to match the templates you developed in the tools you used before, for example, Microsoft Word. But it’s not an easy task to do.

Output formats can control the arrangement of your deliverables since DITA uses semantic tagging rather than format tagging. Semantic tagging helps to indicate the nature of the content. Each output format has the corresponding settings for the target file type. It means that you define how and in what form each element must be included in the output, based on the type of such element: topic, main content, link element, numbered list, etc.

The Pros and Cons of DITA

The most evident advantages of using DITA are the following:

• Content reuse. The same introductions, glossaries, and “how to use” sorts of wording can be used in multiple documents.
• Multi-format output. Deliver content in multiple formats and reconstruct topics to make a customized output. You combine the information in a single content as needed and output it into various formats.
• Single-source your content. Aim information for a certain user type and context. What goes into a user manual will differ from the content of a product overview or a datasheet.

So, basically, you create some topic just once, and DITA helps you use it in multiple deliverables for different purposes. And if you have multiple outputs with overlapping content, it is convenient to use DITA.

However, every story has two sides. And here’s the other side of DITA’s:

1. Integration: it’s not easy to integrate DITA into existing web frameworks. Such frameworks have templates with good display across your devices. Without these, you spend a lot of time on your hands. JavaScript libraries are also a challenge to integrate with DITA. To get it work, you’ll probably have to fit the ax in the helve because the classes and IDs are critical for Java plugins, and, again, you’re spending precious time to solve the issue. If you have some non-DITA content integration of such content with DITA will give you an additional quandary.
2. The “Information typing” aspect is hard to understand. You’ll be figuring out how to structure your content, and complex elements are just a hindrance here. Combining a lot of small topics don’t work so well.
3. Writing in XML is a back-breaker. You must know the order of allowed elements and not just which of them to use. This language is too lengthy and not human friendly, it was created for computers first of all.
4. Customization. If you need to customize your output, DITA is not much of a helper here. To transform XML elements into HTML, you should first customize the XSL-FO (eXtensible Stylesheet Language Formatting Objects) stylesheet.
5. Support. DITA doesn’t support Microsoft PowerPoint, and PDF modification is tricky. The three basic topic types available in DITA work well with tech docs but not always fit for educational content.

You must decide whether you really need such a standard in your work. If you do not update your documents regularly or reuse the same content in various combinations, maybe you can do just fine without DITA.

The next issue is the price: the shift to DITA demands a significant infusion of resources – CMSs can be expensive to implement with DITA. It requires experts to manage the transition. You’ll probably spend a lot of time developing your information architecture rather than writing the docs for your company. In addition to the reliable CMS itself, that you need to buy. This is about an investment of tens of thousands of dollars and 12-18 months of hard work, in some cases, even more. Moreover, staffing is quite a challenge. Not so many people know DITA, that’s why their salaries are high. If put together all these points, DITA may prove to be not so cost-effective. Usually, it’s a bundle for small and medium businesses.

Another problem is acceptance: documentation managers must decide on what to rewrite, reuse, convert, and neglect. It’s not an easy task if you have several managers: each has a certain set of documents that they consider important, so the settling of this issue may raise a conflict, which is time-consuming and may delay the transition considerably.

One more important point is training since DITA is not so simple as one might think. It takes time and money. Some writers like to keep with the traditions and do not like to leave their comfort zone, so they protest against the process. And a technical writer must distract a lot to understand DITA, it’s not as intuitive as they put it.

ClickHelp as the Right Alternative to DITA

Now, when DITA is not just a word for you, and you understand the core concepts, let me tell you about your other option. If you need to make a professional approach to user documentation, you can use ClickHelp. This online documentation tool addresses the same issues much easier.

ClickHelp is a cloud-based tool with no need of installing anything. You can sign up and get your own ready-made portal in the vendor’s cloud. It protects access for authors with SSO, or you can use simple login and password. ClickHelp works in a web browser from any place in the world. You can easily run a review process for your content, publish, and update your user guides quickly.

Let’s have a look at professional technical writing functions that ClickHelp offers and how they cover DITA use cases:

1. Content reuse. ClickHelp helps to make content reuse simple and clear. Snippets and variables are essential for it. You insert a snippet, and it becomes a part of your topic for readers, but for authors, it remains a special entity that can be edited in one place while updated throughout the documents it was used. This way, you save a lot of time maintaining reused content.
2. Multi-format output. You can easily maintain your documentation online and then export it to any format you need.
3. Single-sourcing. Single-sourcing can make any documentation authoring process more efficient. With ClickHelp, you don’t need to make up DITA maps and write XML, you just visually choose what elements should be placed into a certain output with the help of Output Tags.
4. Content styling. While editing topic contents, you can use various styles for the text content – make it bold/underline/italic, change the font size and color, etc. It’s important to stay consistent with such element styling as tables, lists, etc., so your docs look professional. For better consistency, you can manage the styles of those elements in a shared CSS style file that is used in all your articles. A visual editor doesn’t require your understanding of XML. But in case you need to have low-level control over HTML code it allows you to get access to HTML source.
5. Teamwork. When you create a project online as a team, it’s crucial to work in a coordinated manner. ClickHelp comprises a lot of possibilities for Teamwork. All of your team can work on one portal despite their physical location. They can use workflow to assign topics for each other for collective work. To get input from SMEs or let others proofread your content, they can use a review workflow. It’s an integrated teamwork environment, not just an author tool.
6. Publishing and delivery. When your content is ready, you can easily publish docs for readers on your portal. Some of the documents can be password-protected, and some left public. You can freely revise your documents and update one or several topics at once. It can save you a good deal of time since you don’t need to ask a webmaster or IT Department to upload your new files to the site and wait for several days while they have time to do it. As a technical writer, you can manage your documentation site in an efficient manner to save time and effort.

“With ClickHelp, you get a ready-made documentation site with the teamwork functions and documentation hosting.”

Conclusion

Implementation of such standards as DITA is a long-range project that consumes time, money, and human resources. And grasping at new trends because everyone is following them is not the right way to go. Instead, maybe you need to take time, look around, and find another alternative for your documents to be structured. ClickHelp might be just what fits you best – content reuse and dynamic output are paired with the ease of use for better documentation delivery. Give it a try, and you will see that DITA is not the only approach to professional documentation writing.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices