How Adobe’s Technical Writing Tools are Limited

Documentation teams use a variety of tools for creating and managing technical documentation. Some of these tools are purpose-built for managing documentation, while others have been adopted because they were available at the time. Adobe RoboHelp and Adobe InDesign are two popular, long-standing tools used by tech doc teams, which may be helpful in certain situations. However, for most documentation teams, they are limited in meeting today’s documentation needs.

As we’ll show you, there are significant limitations for documentation teams that use RoboHelp and InDesign, including scalability, accuracy, translation, and collaboration, and that structured authoring and component content management (CCMS) solutions are a better fit for scaling and managing modern technical content.

Traditionally, technical documentation was published as PDFs that end users could download or obtain as a paper copy. Although there are some situations where a PDF is still required, it is only one format needed today (and usually the least used one).

Today, users want easy access to technical documentation. They are typically trying to resolve issues or answer questions on their own as quickly as possible, and the idea of having to scroll through pages of a PDF to find what they need is frustrating.

Digital channels that share technical documentation, such as Resource Centers, Knowledge Bases, and Customer Portals, are growing in popularity. These channels provide unique features that make finding information much faster, including search and conversational interfaces.

Additionally, providing technical documentation in digital format enables its view on mobile devices, a channel that is increasingly in demand by mobile support teams, such as field technicians.

The question is, does managing technical documentation in RoboHelp or InDesign enable documentation teams to support these new publishing channels? The answer isn’t a resounding yes or no; it’s more nuanced than that. But there are key considerations that impact what either of these tools can realistically deliver.

To understand the limitations of RoboHelp and InDesign, we first need to describe what these tools are and how they work at a high level.

Adobe InDesign is a desktop publishing application used by graphic designers to create visually appealing documents that can be published in both print and digital formats. InDesign is part of the Adobe Creative Suite and is available as a subscription service. Like some other applications in the Creative Suite, InDesign is an application you download and use on your desktop; cloud solutions are limited to file sharing.

The most popular use of InDesign is in marketing, where it is used to create brochures, e-books, magazines, and other marketing collateral for both digital and print purposes. You can even create really nice interactive documents with buttons, slideshows, animations, audio, and video.

Adobe RoboHelp is a Help Authoring Tool (HAT), used to provide help content, typically to applications. Like InDesign, RoboHelp is also a desktop application that is purchased on a subscription basis within the Creative Cloud.

One popular use of RoboHelp is to integrate it with Adobe Experience Manager, providing in-application help and website help content. While it is still actively supported, you don’t hear as much about innovations and new capabilities in this application as you do with other newer Adobe applications.

It’s easy to understand why RoboHelp is used by technical documentation teams, especially those with a strong Adobe software footprint. RoboHelp is designed to create and manage technical documentation, typically for use as help content published using the RoboHelp Server, Adobe Experience Manager, and into Knowledge base solutions like Zendesk, Salesforce, and ServiceNow.

InDesign, on the other hand, seems like a less likely tool for creating and managing technical documentation for a variety of reasons, but particularly because it only enables teams to create a single document at a time, mixing content and format (much like working with Word or Google Docs). Its use historically comes from the popularity of Adobe’s creative tools in organizations.

However, as we’ll show, InDesign, and to some extent RoboHelp, are not designed for today’s multi-channel, collaborative, structured documentation needs.

Let’s look at several key aspects of managing and publishing technical documentation, and how they are (or aren’t) supported by InDesign and RoboHelp.

You can manage technical content using both a structured and unstructured authoring model, but if you want to get the most out of your content, you’re better off using a structured authoring tool.

With InDesign

InDesign is an unstructured authoring tool. Like Microsoft Word or Google Docs, an InDesign file follows a what-you-see-is-what-you-get (WYSIWYG) model, combining content with formatting and styles. Content is written or copied into InDesign frames, which you then format and size to fit the page. The same principle applies to adding images to your document.

In most cases, technical writers create their content in a Word document and then copy and paste it into InDesign; it’s rarely used to create content from scratch. You can also “place” a Word document into an InDesign file, effectively linking the content. When you use the “place” approach, any changes made to the original Word document are updated in the InDesign File when you open and refresh the file. You will need to review your file, however, as changing the amount of text can impact the design of the content in the file.

Adobe has also introduced a new tool called InCopy that technical writers can use to create technical content that is synced with the content in the InDesign file. The InCopy tool effectively replaces using Word, and the same challenges still apply in terms of fixing formatting issues.

The key point to note is that although it is easier to keep the InDesign file up to date as you make changes to the Word document or InCopy content, you will still need to republish the content and place it in the appropriate publication channels, which means your changes are not real-time.

As the content is unstructured and is created on a document-by-document basis, there is no content reuse across documents. Each document stands on its own, leaving tech writers to duplicate content in each document they need to create. You do have the ability to create snippets of content, but these are saved as standalone files that you then “place” or embed into your documents. You will need to track where you use these snippets manually; the same process applies for publishing updates. You do not have the option to reuse content using variables, filtering, or profiling.

With RoboHelp

RoboHelp also follows an unstructured content authoring model, but you may find you have a bit more flexibility. With RoboHelp, you create a project with a collection of topics. Each topic includes a mix of content and formatting using a WYSIWYG editor. You can assign keywords or phrases to topics to help create an index and then, using templates, publish that content to different channels.

RoboHelp does provide more reuse capabilities than InDesign. For example, you can create reusable snippets of content. However, these snippets can only be used within the project in which they were created, and a project is typically a single document. You can also use tag groups to create conditional content to support filtering or profiling.

The Impact: If you are managing only one or two documents with little content reuse or need to use variables and filtering, then either of these tools may work well for you. However, when you start adding more documentation that needs to be personalized for different audiences and published across multiple channels (each one looking very different), then structured authoring tools will suit you much better and be more cost-effective in terms of both resources and tool costs.

The ability to collaborate on technical documentation is essential because writers work closely with subject matter experts and editors to create the most accurate content possible. Because both InDesign and RoboHelp are desktop-centric, not cloud-native, collaboration is a bit more challenging, requiring extra steps you don’t need with a cloud-native tool.

With InDesign, there are three approaches to collaboration. The first is to export the content to PDF and share the document with team members. These team members would then annotate and comment in the document and send it back to the writer, who would then need to make the changes in the original InDesign file manually. You can also share the InDesign file directly with others, but this requires each reviewer to have an InDesign license and to be familiar with working in InDesign. Additionally, only one person can work in an InDesign file at a time, so you may face challenges in managing reviewers’ work.

The third approach to collaborating on InDesign files is to upload the file to Adobe Creative Cloud as a cloud document and share it for review. Again, reviewers would annotate and comment, and the writer would then need to manually apply those changes to the file.

It’s a similar story with RoboHelp. You upload the content to cloud storage in the Creative Cloud and share a URL with reviewers. Reviewers need to use the RoboHelp Review Web App to access and collaborate on the content.
As for version control, neither tool has it out of the box. With RoboHelp, you need to integrate a tool like Git to manage versions of your content. With InDesign, versions are maintained by publishing the file as a PDF or saving multiple copies of the InDesign file for each version you need.

The Impact: Again, the biggest impact is felt by tech doc teams that work with numerous reviewers and subject matter experts, as there are more people to manage when working on documentation and tracking changes made. Additionally, if your organization must comply with strict regulations, these tools may not be the right choice, as tracking versions and auditing are not built-in features.

Not every company needs to provide its technical documentation in multiple languages, but for those that do, InDesign and RoboHelp provide significant limitations.

To translate InDesign files, you export the content as IDML and then send the content for translation. When the translated content is returned, you typically create a copy of the InDesign file for each translation and import the translated content into the appropriate file. Now, you are managing multiple copies of your document, one for each language, and you’ll need to track changes to the original language manually, as well as when those translations are updated. When you apply translated text to the file, you may need to do some formatting work, as translated content is typically larger in size than the original content (assuming your base language is English).

RoboHelp is a similar story. You manually translate content by exporting a translation file, sending it to a Translation Management Provider, and then importing the translated content. For each language, you create a new Project.

RoboHelp also offers a machine translation approach in newer versions of the tool. Using this approach involves selecting topics or an entire project and sending them for translation. The translated content is then returned and placed in a new language project that is connected to the source project. When the source content is updated, a notification appears indicating that the languages need to be updated.

The Impact: Translation is not inexpensive by any means, but when you have to build manual workflows that require translating the same content repeatedly, even with minor changes, your budget will take a hit. Additionally, manually managing multiple copies of a document and ensuring all translated versions are up to date is a headache that no technical documentation team wants to deal with.

We talked a bit already about publishing content from both RoboHelp and InDesign, but there are a few more things to consider.

First InDesign: The primary publishing format for InDesign is PDF, both for printed and digital use. You can also publish an InDesign file as an interactive PDF, HTML 5, XML, ePub, TXT, and RTF. The key point to remember with InDesign is that there is no way to automate publishing updates; it’s a completely manual process.

Then there’s RoboHelp: The primary publishing channel is RoboHelp Server, which is a server-based Help solution. You can also publish a project to Adobe Experience Manager, SharePoint Online, and knowledge base solutions, such as those already mentioned. Within your project, you define output layouts, skins, or templates for different formats.

In terms of formats, RoboHelp content can be published as HTML5 (responsive and frameless), PDF, MS Word, ePub/Kindle, Mobile App, Knowledge Base, and content-only (XML).

The impact: While there are a number of options for publishing RoboHelp content through automated processes, InDesign does not offer the same capability. If you need your technical documentation published quickly and with minimal manual effort, InDesign may not be the best option for you.

When selecting a tool for creating and managing technical documentation, it’s essential to clearly understand your requirements before starting your search.

If you have only a few documents, little reuse, few publishing channels, and no stringent regulations or compliance requirements, then either of these tools might work for you. If you are an Adobe customer, it makes sense to examine these tools closely.

But the more documentation you need to manage, the more languages, publishing formats, and reuse, these tools have limitations that will restrict you and cause a strain on your resources – both time and money. Structured authoring tools make a lot more sense when you have these constraints; even more so if you have to deal with regulations and compliance requirements.

There is no one right tool for managing technical documentation that works for every organization. The right tool will meet most, if not all, of your organization’s (and your tech doc team’s) specific needs.

To get you started, here’s a quick checklist you can use to start documenting your requirements. Add any additional questions based on your situation:

1. How many products do we support?
2. How often is our content updated?
3. How much content do we reuse across our documentation?
4. Do we need to use variables in our content (e.g., different product names in different markets)? Or do we need to apply filters or profiles for different audiences or markets?
5. How many languages do we support?
6. What formats do we need to publish our content?
7. What channels are we publishing our content to?
8. How fast do changes to documentation need to be published?
9. How many team members do we have? How many are remote and will need cloud-native tools?

We began this blog by stating that there are many different tools technical documentation teams can use to manage content. And there are. However, not all options are the right choice, and it’s essential to understand the limitations of each tool in relation to your specific requirements.

Adobe InDesign and Adobe RoboHelp are both practical tools for specific purposes. While we agree that RoboHelp can serve as a technical documentation tool, its limitations in terms of structured authoring pose challenges for organizations that need to scale their documentation. InDesign, on the other hand, is not purpose-built for technical documentation, unless your requirements are very light.

Structured authoring and a component content management solution (like Paligo CCMS) are the best approaches for most technical documentation teams because they provide the modern capabilities needed to manage highly reusable, scalable documentation.

Define your requirements and carefully review potential tools. Then pick the one that works best for your company. If you’d like to learn more about CCMS, drop us a note and we’ll show you how Paligo CCMS can help manage your documentation.