[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

Let’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:

• Flexible output – Topics can be strung together like beads to create different outputs. This may let technical communication be more active in supporting our company’s business strategy.
• Re-usability – Chunked content can often be used in multiple projects and outputs.
• Multi-author capability – Chunked content lets multiple authors work on the same project.
• Consistency/accuracy – One owner writing a chunk once means more consistent content with fewer errors.

It’s not perfect:

• Newness – Topics are chunks of content with no continuity between them. This requires a new way of writing.
• Re-use constraints – Although content chunks can be re-used, that may be difficult in situations requiring very different writing styles such as tech support versus marketing.
• Chunk proliferation – If a topic is the smallest granular unit of content that answers a question, defining the questions is crucial. It’s easy to get too granular, like making each field description a separate topic, but the number of topics can quickly become unmanageable.

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:

• Topic Authoring – The basic standard unit of content in RoboHelp is a topic. By definition, this makes it a topic authoring tool.
• Master Pages – To create templates to ensure consistent structure and common content and let you focus on topic-specific content. (Creating master pages before you start your projects adds a neat side benefit. The “objects” on those master pages, like head levels, bulleted and numbered lists, Note, Tips, and so on also comprise the objects to be defined by the CSS.)
• CSS – To specify format settings for your content in general and tables in particular.

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:

• Stick to the rules (master pages and CSS).
• Don’t tweak.

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:

• 
• Working in RoboHelp, without DITA, is conceptually and technically simple. With a DITA tool, the concepts and technologies are more complex and you’re likely to need more of a techie on staff.
• Working in RoboHelp, without DITA, provides total authorial flexibility – you make the rules (for better and worse). DITA’s structural rules are rigid, enforced, and can’t be easily modified.
• Working in RoboHelp, without DITA, requires a very brief startup analysis and design period. You can do this work yourself in a week or less. In DITA, this is likely to take longer. For example, if you realize that you forgot to create a master page for a particular type of topic, you can create one at any time in a few hours. With DITA, however, many consultants will suggest that you work for a year using the predefined information types in order to get used to working in DITA before creating new custom types.

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:

• Part 1: Setting the Help Hooks: Context Sensitive Help Using RoboHelp
• Part 2: Single Sourcing With RoboHelp