Newsletter Archives: June 2002 Columns
Single-Sourcing SIG-What Are We Using, Anyway? | When to Use Single-Sourcing | Single-Sourcing with AuthorIT®

 

Char James-Tanny is well known in the Help community for her knowledge of online Help tools and concepts. Author of two books, she speaks frequently at conferences around the world on advanced Help topics, cross-browser issues, and tool-specific functionality. Char lives and works in Lynn, MA, with her husband, five-year-old son, three dogs, and fish.

 

by
Char James-Tanny

Single-sourcing with AuthorIT®

 
 

Ask three people to define single-sourcing and you’ll probably get four answers. For some reason, getting a definition is elusive at best and misleading at worst.

My definition of single-sourcing is:

  • I can create multiple outputs (WinHelp, HTML Help, HTML, JavaHelp, Oracle Help, or Print) from one source.
  • I can target a specific platform or media (in other words, I can use conditional text).
  • Generation requires little more than a click or two.
  • Print output doesn’t require any editing and it includes things like Word cross-references in place of my hyperlinks.

And the tool I choose to use for single-source projects is AuthorIT. In addition to my single-source definition, AuthorIT is a multi-authoring tool, uses dynamic check-in/check-out, provides group and user settings for permissions, and includes version control and variables, plus more.

 

Introduction

AuthorIT is distributed by AuthorIT Software of Auckland, New Zealand (Web site: http://www.author-it.com). Several versions are available (Desktop, Workgroup, and Enterprise), plus optional modules (Project Management, Offline Authoring, and so on).

You may be wondering why I don’t use Quadralay WebWorks® Publisher Professional. The simple answer is, I don’t use Adobe® FrameMaker. If you use FrameMaker, then you probably want to look at WebWorks as your single-source option. But if you don’t use FrameMaker, then you want to look at AuthorIT.

AuthorIT is more than a Help Authoring Tool (HAT), as it provides content management, an optional project management module, and more. Unlike some of the other HATs, you can use AuthorIT as a document repository if your company frequently reuses information (such as law firms and banks).

As a result, AuthorIT uses some different terminology:

Library: a container for all information for all projects. Most companies would have one library, although consultants would have one library per client. AuthorIT’s library is a relational database.

Object: a piece of a project. Everything is an object: topic, a piece of a topic, graphic, hyperlink, and so on. AuthorIT is an object-oriented documentation system.

Media object: a specific object that controls the look and feel of the different outputs.

 

Workflow

When you first start working with a new tool, you’re usually a bit overwhelmed with the options. AuthorIT includes defaults for the basic styles and media objects, which lets you deal more with the “getting started” aspect.

The basic workflow in AuthorIT is similar to the basic workflow in any HAT. You create or open a book, then add your topics. However, while other HATs might let you ignore structure, AuthorIT tends to enforce it by requiring that a book is open when creating a topic (you can override this, if desired).

AuthorIT also lets you re-use topics and books as necessary. You can create books with various levels of content and mix-and-match books as necessary. In some cases, you might want to embed one topic in another, rather than just re-using it.

You can import existing documents into AuthorIT, including Microsoft® Word® documents, WinHelp-coded RTF files, and FrameMaker MIF files (with the optional add-on). AuthorIT uses the headings to maintain the structure of the document and converts formatting according to the styles. (AuthorIT will not convert manually formatted paragraphs and characters, except for bold and italic. All formatting must be done through a style.)

When it’s time to generate your output, you’re presented with a list of books in your library and check boxes for the different outputs. Select the outputs you want and click Start. AuthorIT takes care of writing the necessary code, including HTML 3.2 for JavaHelp and HTML 4.0 for Oracle Help. You can create multiple outputs at one time, although this depends on your system, as generation can be memory-intensive. (You may want to generate one output at a time.)

 

Benefits

You’re probably thinking that other HATs let you do something similar, and that is correct. You update the content in one project, then update it in another by copying or importing. The difference with AuthorIT is that once you update a topic, the changes immediately propagate throughout the library. You don’t have to open any other project, book, or topic.

This part of the workflow means that employers and clients benefit because it takes less time to update the content. Writers benefit because all information is immediately available in one place: the library. Enhance output by using conditional text to include and exclude information at the character level. If you have ever dealt with the graphics debate (“should they be included in the Help or not?”), you know that opinions vary. With AuthorIT, you can include or exclude graphics from any output. If you use linked graphics, you can select to use different graphics for different outputs (for example, standard GIF in Word, a SHG file in WinHelp, and an image map or animated GIF in HTML). And you can take advantage of variables to store changeable information, such as a product or company name.

For example, I was once asked the easiest way to change a product name in a file-based development system. This product name was used throughout 2,000+ topics, including the file names. With any other tool, a global search and replace on the topics would be followed by changing file names individually and then verifying the links. In AuthorIT, this same change would involve changing the variable name.

What about your users? They benefit, too, although they may not realize it. You will, however, when support calls decrease.

  • No one will be calling to complain that the information in the tutorial conflicts with the user guide.
  • Printed documentation can include embedded target topic information in place of hyperlinks in the current topic. This means that users don’t have to flip through a user guide to find a definition or other pertinent information.
  • Users can take advantage of hyperlinks in the printed documentation, which are converted to Word cross-references (and are linked if the document is printed to an Adobe® Acrobat® PDF file).
  • HTML files are small and clean, downloading quickly over a dial-up connection.
  • Server-based CGI full-text search results in faster searches and doesn’t require that JavaScript™ is enabled on the user’s system.

For example, in one of my projects, I was able to create a training manual by embedding content from the user guide and then adding exercises. The training manual was 312 pages, with 23 pages of exercises and no more than 5 pages of new content. Therefore, 89% of the training guide was re-used information and 11% was new information. By simply using drag-and-drop to embed topics, I’ll realize a time savings when I update, because the training material will be updated simultaneously. This, of course, results in a cost savings for my client.

 

Savings and Costs

Whenever you’re talking about development, savings are important. AuthorIT provides both cost and time savings.

Let’s say that you need to create a user guide with 1,000 topics in online and printed formats. The time to develop the topics doesn’t change. However, the time to generate the printed output does. In some tools, you have to spend hours reformatting, restyling, and applying the correct template with its headers and footers. With AuthorIT, you just generate the output. (Note that some HATs do create printed output correctly.)

Now let’s say that you need to use your user’s guide to create a tutorial. In AuthorIT, you create a new book, then either drag existing topics into it or create new topics and embed existing topics. (It depends whether you want to add more information to the topic that pertains only to the tutorial.) In other tools, you have to create a new project and import the pertinent information, which means that you have two projects to maintain.

For the project I mentioned earlier, I spent 200 hours creating the User’s Guides. I spent 20 creating the corresponding tutorials (which included testing the exercises).

I typically recommend the Workgroup ($499) version for consultants and the Fixed Enterprise ($699) version for my clients. (The Fixed Enterprise version is a better choice for multi-authoring over a network.) For a complete pricing matrix by country, see http://www.author-it.com/pricingwiz.mv.

Source of this article is cjt-AIT_SS_sb_final.doc, 06/2002

 

The opinions expressed by contributors to the Society for Technical Communication (STC) World Wide Web site are solely those of the individual writers and do not reflect the opinions of STC, the members of the STC administrative council, or STC World Wide Web volunteers.

Reference herein to any specific commercial firm, commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not constitute or imply its endorsement, recommendation, or favoring by the Society for Technical Communication (STC).