Content reuse the easy way

For years you've been hearing about how structured authoring and XML-based workflows can help technical authors reuse content more efficiently. By converting all of your topics to an XML standard, investing in a CMS, and building custom DTDs and XSLT translations, you can avoid having to maintain duplicate content.

The downside? Months of time invested in research, evaluation, and conversion only to be followed by a steep learning curve as your team adjusts to a new workflow. And then there's the price tag for the CMS, editor, and maybe some consulting fees to ease you through the difficult parts. Such implementations can cost in excess of six figures for larger organizations.

Does reuse have to be so painful?

In short, no.

The good news is that many technical writers can reuse content efficiently with their existing tools.

Quite a few authoring suites support features for content reuse. Under the hood, they work just like DITA conrefs or other forms of XML inclusion; you write some tagged content in a separate file, replace all instances of that content with a cross reference, and the HATT replaces those cross references with the full text when you generate your output.

For example, the product suites from Adobe, MadCap, and Author-it all allow you to reuse blocks of content across topics or documents. You can use snippets for duplicate content at the paragraph level, and variables at the word or phrase level. MadCap Analyzer and Author-it Xtend are particularly helpful because they analyze your documentation for redundant content and suggest reuse.

Such features are not available to most authors who have moved to a custom XML workflow; often these writers resort to memory for tracking content reuse. At best, they must invent complicated metadata schemes for finding existing content, and actively search the database when they suspect duplication. Why not let the tools do it for you?

Also, most of the HATT tools combine editing, project management, and publishing features into a single interface, and publish output that is user friendly for a technical communications audience. If your goal is to reuse content, why bother reinventing your navigation scheme using XSLT and purchasing a license for third-party search functionality? Stick with the tools that publish output you need, and reap the benefits of a familiar workflow.

Instead of revamping your workflow completely, you can spend your time focusing on how your content is structured and rewriting it for more efficient reuse.

I'm constantly seeing quotes about how people were able to reuse a large percentage of content by moving to a custom XML workflow. But doesn't that percentage have more to do with how their content is written than the tools and workflow they chose? If there is 80% redundancy in your content, you'll likely gain 80% reuse whether you choose the complicated home-brew XML solution, or just use the snippets feature in your HATT. It isn't about the tools, it's about the writing.

Before you invest major resources in a move to XML, consider whether reuse is your only goal. If so, maybe your existing tools will do the job just fine.

That said, there are situations where custom or standards-based XML solutions are optimal. For example, they offer a very high level of flexibility. Writing a custom XSLT transformation gives you full control over the appearance of your content. Also, standard formats such as DITA are highly portable if you need to change tools.

Don't just assume you need a custom XML workflow to gain the benefit of content reuse. Chances are you can manage duplicate content efficiently and lower your overall word count without sacrificing the robust features of a dedicated help authoring tool.

See also: Structured authoring - 10 questions to ease the transition.

RoboHelp basics

RoboHelp is an industry-standard tool for creating user assistance. Let's chat a bit about the basics of creating help with this tool.

Adobe RoboHelp is a topic-oriented tool. Each topic has an individual topic id assigned for easy reference and linking. You can view topics by ID or topic title in the Project Manager pod.

The best way to approach help authoring with such software is to first outline the tasks and concepts you need to document. For example, if you are creating documentation (help topics) for a software application, begin by looking over your specs or the actual app. What tasks can be performed? Create topic stubs for each. Also, create an overview topic with conceptual information to tie the tasks together.

RoboHelp Projects

When you create a new project, RoboHelp allows you to specify some basic settings for the project, including a default topic, navigation settings, and an output type. RoboHelp generates help in several formats; the browser-based WebHelp is a popular format because it uses standard HTML files. The AIR help format is becoming increasingly popular also. You can also create Flash Help, WebHelp Pro (server-based help), and print output for MS Word.

Navigation options include a table of contents (TOC), full-text search, glossary, and index. These are presented in a separate pane in the published output, so that users can view the navigation and topics at the same time. Most of the navigation can be altered with in-tool editors. The search is generated automatically when you generate your output.

During the setup of your RoboHelp project, you will choose options in the Single Source Layouts dialogs that specify your default output and the navigation settings.

After setup, you can access resources in your project using the Project Manager pod. This pod contains a list of all of the topics you have created, any images stored in the project, and the Table of Contents and Index entries that you have defined.

RoboHelp editor

RoboHelp features a WYSIWYG editor and a code view. This allows you to work under the hood when you wish. Also, there are several handy tools available for creating dynamic HTML effects and so on. In addition to written content, you can insert images, video, PDF documents, and other resources into your help topics. Some of these can be embedded directly, and others can be accessed via hyperlinks. RoboHelp tracks all of the resources in your help project using XML baggage files.

If you decide not to use the internal editor, you can specify a third-party editor. When you click a topic in the Project Manager, RoboHelp will open the topic in the editor you have chosen.

Output

After you create your project and write your topics, you can generate the project and view the output.

You can also link your help into the applications you are documenting. This is known as context-sensitive help, because you can link specific topics to the appropriate features in the application interface. RoboHelp offers several APIs for linking topics into your software applications. View the help topics in RoboHelp for details. In some cases you will need a map file to help you associate topics with individual GUI components.

You can buy RoboHelp as part of the Adobe Technical Communication Suite 2.