Adobe for Technical Communicators, Switching to the Mac

This article appears in slightly different form in the March/April 2008 issue of IEEE Micro © 2008 IEEE.

This time I talk about two subjects that are not the way they once were and may change again tomorrow.

Adobe Technical Communication Suite (Adobe, San Jose CA, www.adobe.com, $1599.00)

Fifteen years ago, the tools of the technical communicator's trade came from many companies. The most important tool for creating technical manuals was FrameMaker from Frame Technology. For newsletters, marketing pieces, and other short documents, writers also used the more agile PageMaker, a tool for composing pages, from a company named Aldus. RoboHelp, from Blue Sky (later called eHelp) emerged as the tool of choice for creating online help systems. When web browsing became popular, Macromedia brought out DreamWeaver, the HTML editor of choice. Macromedia also developed Flash technology, one of the simplest ways to add animation to online content.

Starting in the early 1980s, a company called Adobe invented Postscript, the display language that now sits inside virtually every laser printer. They also developed the premier tools for manipulating vector and bitmapped graphics: Illustrator and Photoshop. Postscript is great for the insides of printers, but not so good for interchange and multimedia, so in the early 1990s, Adobe developed Portable Document Format (PDF). More than 90% of personal computers have software to read PDF files.

When many companies serve the same customers with different products, there is usually one outcome -- one or more companies grow by absorbing the others, and soon the customers have a small number of full service suppliers.  Adobe now owns all of the products mentioned earlier in this column. Only Microsoft has a plausible claim to being a competitor.

Having accumulated a set of products for the same audience, Adobe has taken the added step of making them work together smoothly. The Technical Communication Suite (TCS) consists of FrameMaker, RoboHelp, Captivate, and Acrobat 3D. If you buy them as the TCS, they work more efficiently together, and cost less, than if you buy them separately. 

For technical communicators, FrameMaker and RoboHelp are the heart of the TCS. Captivate, which simplifies creating Flash-based demonstrations and training, may become more popular as buyers of the TCS learn how to use it. Acrobat 3D, for most technical communicators, is essentially the same as Acrobat, but with a flashy new feature (embedded 3D graphics) that most of them will never use.

FrameMaker is the tool most technical communicators choose to create books. It manages the chapters, appendixes, indexes, and so forth in a structure called a book file. It provides ways to maintain consistent styles and formats throughout the final document. It provides a facility for including some text conditionally, based on attribute values applied to the document at publication time. Up until the TCS, FrameMaker worked with a product called WebWorks Publisher to produce HTML output from the same source files. In the TCS, RoboHelp provides HTML publishing capabilities for FrameMaker.

I first reviewed FrameMaker in the May/June 1993 Micro Review. Unlike the current version, FrameMaker 3.0 worked essentially identically on both Macintosh and PC, as well as on the Unix systems for which Frame Technology had originally designed it. FrameMaker 8 and the TCS work only in a Microsoft Windows (XP or Vista) environment. Adobe has given no indication that they will ever support this product in the Macintosh environment. On the other hand, FrameMaker 8 has a variety of new or improved features, when compared with FrameMaker 7.2:

• Change tracking -- at last!
  
• A tabbed view to facilitate working with many source files simultaneously
  
• Improved Unicode support
  
• Spelling and hyphenation dictionaries for 30 languages
  
• Better XML support (but still no DTDs or schemas)
  
• Support for Darwin Information Typing Architecture (DITA)
  
• Integration of rich media (for example, Flash or 3D graphics)
  
• An updated Frame Developer's Kit (FDK)
  

Like any new version, FrameMaker 8 has given me a few unpleasant surprises. I encountered, as others have reported, occasional crashes or failures to complete requested operations. However, I did two serious projects with FrameMaker 8 and was able to get past the occasional problems to produce correct PDF output.

Most technical communicators who produce online help use RoboHelp to do so. It facilitates building a body of information units called topics. It provides ways to maintain consistent styles and formats, and it manages all the ways end users can navigate to and among the topics. There are many standard formats for online help -- nowadays all based on HTML -- and RoboHelp supports all of them from a single source.  

I first reviewed RoboHelp (version 2.6) in the Sept/Oct 1994 Micro Review. Over the succeeding years, new RoboHelp versions came out much too frequenty, leading to internal problems in the product. According to Mike Hamilton, a former key eHelp employee, Adobe inherited a code base in December 2005 that needed massive reorganizing and bug fixes. Another problem with RoboHelp was its output of a proprietary form of HTML, based on the notorious tags. Adobe began to attack these problems with RoboHelp 6. They have now brought out RoboHelp 7 as part of the TCS.

In the TCS, RoboHelp works well with FrameMaker. Like FrameMaker, RoboHelp provides styles, variables and conditional text. You can define a mapping between FrameMaker's sytles, variables, and conditions and RoboHelp's. The mapping facilitates importing FrameMaker output into RoboHelp. You can import FrameMaker files into RoboHelp by reference, so that RoboHelp receives subsequent changes to the FrameMaker file, or you can import as a copy, so that subsequent changes to the FrameMaker file do not affect the RoboHelp version.

RoboHelp can also import files of a variety of formats, including Microsoft Word 2007, as well as earlier Word formats. It converts all imported files into HTML and provides a built-in HTML editor for manipulating them.

RoboHelp projects generally contain large numbers of files, sometimes worked on simultaneously by more than one person. RoboHelp comes with a source control facility that provides locking, history, and a means to compare versions. 

Captivate is new to most technical communicators. It provides ways to create simulations (annotated animated screen captures) and training materials, including quizzes. Captivate produces Flash output, so that file sizes are relatively small. It can even import PowerPoint presentations and convert them to Flash.

Acrobat is an essential tool for technical communicators. It has many quirks, and there are gurus to help you deal with them (see Micro Review Sept/Oct 2004). It provides a way of publishing reasonably sized files representing printed manuals. It provides a variety of means for reviewing and annotating documentation. 

In the TCS, Acrobat enables you to embed three dimensional figures -- the output of common computer-aided design programs -- in PDF files. Readers can then manipulate the figures without special software. You can also embed Flash, sound, and other multi-media formats. 

The way I use Acrobat, I've noticed little difference since moving to the TCS. My one complaint is that printing generally takes longer. There are some documents I print routinely that used to come out quickly with my old version of Acrobat but now take so long that the printer manager sends back an error message saying that the document failed to print. If I ignore the message, the document eventually prints. I've only tried this with one printer -- my ten-year-old HP LaserJet 4000 -- so perhaps it's not a general problem.

Adobe has made it easy for technical communicators to adopt the TCS. The bundle price essentially gives you some components at no cost. Adobe also offers generous discounts to owners of earlier versions of any of the components. It also offers student discounts. 

By bundling the products of the TCS, Adobe makes it less likely that a competitor to any of these products will become a new standard. An example of such a competing product is Flare, from MadCap Software. When Adobe acquired Macromedia, which had recently acquired eHelp, members of the RoboHelp team left Adobe to found MadCap. This gives MadCap Flare immediate credibility among technical communicators. Adobe's bundling of RoboHelp into the TCS, however, creates a large barrier to a successful challenge to RoboHelp by Flare. 

If you produce technical documentation, you probably already use FrameMaker or RoboHelp. You should take advantage of this package to obtain the benefits of the greater integration. It will also give you Captivate and the 3D features of Acrobat, essentially free.

Switching to the Mac, Leopard Edition: The Missing Manual by David Pogue (O'Reilly, Sebastopol CA, 2008, 604pp, ISBN 978-0-596-51412-9, www.oreilly.com, $29.99)

In 1984 I got my first Apple Macintosh computer, and I used Macs almost exclusively until the early 1990s, when Windows 3.1 became a serious competitor. Gradually I switched almost entirely to PCs. I haven't done any serious work with a Mac in many years.

Recently I had occasion to borrow a Mac to review some Mac software. I found the experience extremely frustrating. I know that a Mac can do essentially everything a PC can do, but they do it differently enough that I felt like a beginner. It reminded me of times when I've tried to express myself in a language I don't know very well. I know what I want to say, but I don't know how to say it in that language. My mind races ahead, but my tongue cannot follow. This is the problem that David Pogue attacks first. The first four chapters tell you how to accomplish things on a Mac that you already know how to do on a PC.

If you're not just visiting, but actually emigrating from the PC to the Mac, there is still a lot more to do. You need to move your files and get used to a whole new set of application programs. While some programs work exactly the same in both environments, you may find yourself using a different browser or mail program. Many programs work almost exactly the same. Pogue lists the tiny differences to be aware of in dozens of common programs.

The remainder of the book is not so much about switching as about understanding how the Mac OS X operating system works. For example, you probably have a limited view of how networking or system preferences work in the Windows environment. Pogue explains the somewhat more comprehensible Mac versions of these subjects.

If you are a PC user, and you need to use a Mac or are considering moving permanently to a Mac, this is an essential book. Don't leave your PC without it.