[Guest Post] “Like Beads on a String: Structured, Topic-Based Authoring in RoboHelp”, by Neil Perlin

Welcome to the last of three posts covering questions that I often hear about RoboHelp. In this post, I’ll look at structured, topic-based authoring – what it is, whether and how RoboHelp supports it, and if it requires DITA. This post summarizes a related webinar; you may view the recording with this link: ADV ROBOHELP 3: Like beads on a string: Structured topic-based authoring in Robohelp.”

Definition

01 counting-bead-string-10-5261-pLet’s start with the simplest part of the term, “topic-based”. Topic-based authoring means authoring content in small chunks, or topics, rather than large chunks, like documents or books. Is this new? No. RoboHelp and Doc-To-Help debuted topic-based authoring 1991, and the concepts date back to 1965 when Robert Horn did the work that formed the basis for InfoMapping.

A “topic” is a single chunk of content that contains as focused and self-contained as possible a discussion about one subject. “Focused” in that it answers one question – “How do I …?”, “What is …?”, etc. “Self-contained” in that it contains all the information immediately needed to answer the question; related information is in other topics linked to the primary topic.

Now for the more complex term part. “Structured authoring” simply means authoring with structure but doesn’t define what that structure is or how it’s applied. What is “structure”? Keeping things simple, it’s a set of standard and consistent sectional, syntactical, and stylistic rules. Technical communicators have always created this type of structured content, albeit manually. What’s been changing is the importance of that structure and how we create it.

There are several ways to create structured content. The simplest is to define a structure by using topic type templates and a stylesheet (CSS). The template defines the sequence of the sections within topics and the CSS controls the format of the content within those topics. RoboHelp has supported this simple approach for years, doing everything except enforcing the structure. I’ll look at enforcement at the end of this post.

Benefits of topic-based authoring

Structured, topic-based authoring offers many benefits including:

It’s not perfect:

Can you do this kind of authoring in RoboHelp? Certainly. The features you need are right in front of you on the interface.

Structured, Topic-Based Authoring Features in RoboHelp

For details about the features, see the recording of the webinar at <*MAX*>. Here I’ll just sum them up:

In brief, the steps are:

  1. Define the types of content you create – concept, procedure, reference, troubleshooting, etc.
  2. Create your RoboHelp master pages based on the content type definitions.
  3. Create a CSS based on the objects in your content types and apply it to the master page(s).
  4. Start writing. But now, rather than creating new topics using RoboHelp’s default master page, you first ask what type of topic you’re creating, select the appropriate master page, and then start writing following the prompts in that master page.

How difficult is this? Surprisingly, not very. You’ll have to analyze your content types and create master pages and a CSS. (The master pages and CSS are individual files (HTT and CSS, respectively), so you can share them with other projects, spreading the cost of the analysis and design behind these files.) Based on experience, you should be able to define and create the master pages and CSS in a week or less.

The hard part is mental – changing how you work. You have to develop the discipline to follow the two basic rules of structured writing:

Where Does DITA Fit In?

I didn’t discuss control in the previous section. The only thing that prevents you from breaking the rules or tweaking is professional discipline and rules laid out by management. If this isn’t enough, you want to look at DITA.

DITA is a standard for defining and enforcing rules for content structure. You can define structure rules without DITA but there’s nothing enforcing them. So using DITA sounds logical, but consider:

So DITA is a very different environment than RoboHelp. Why would you use DITA? Typically, you can make the case if you have very large volumes of content to write, and/or you need to translate that content into many different languages, and need rigid enforcement of structural standards to do that cost-effectively. Otherwise, DITA may be overkill and RoboHelp will meet your needs.

Summary

Is RoboHelp a structured, topic-based authoring tool? Simply put – yes, and an extremely powerful one as long as you clearly define your “structural” needs.

See also the other two parts of this Series from Neil Perlin: