Adobe Technical Communication Suite 4: A Review

By Alan Houser

What’s the first thing you notice about Adobe Technical Communication Suite 4?

Adobe Technical Communication Suite 4 LogoIt’s big. It starts with a 7 Gigabyte installer file. That’s to be expected, because TCS4 includes five big, feature-rich applications, plus several smaller applications. Some people make careers out of mastering any one of the five major component applications. If you have a task in technical publishing, it’s very likely that TCS4 will provide the right application, or combination of applications, to complete your task.

TCS4 includes the following major applications:

  • Adobe Acrobat X – Review/approval. Forms. PDF publishing.
  • Adobe Captive 6 – Interactive software demonstrations, simulations, assessments.
  • Adobe Illustrator CS6 – Vector-based graphics. Adobe Illustrator replaces Adobe Photoshop, which had been included in previous TCS versions.
  • Adobe RoboHelp 10 – Online help authoring and publishing.
  • Adobe FrameMaker 11 – Authoring and publishing to print or PDF, in both unstructured and structured/XML modes.

You will also find the following minor applications

  • Adobe Presenter – Demonstration videos and screencasts. Adobe lists this as a major application. One could argue about this. While Adobe Presenter is a Very Cool Tool for recording “talking head” videos and screen demonstrations, it’s not nearly as feature-rich or complex as the other five major TCS4 applications.
  • RoboScreenCapture – Screen captures.
  • RoboSource Control – Version control for online help projects.
  • Adobe Bridge – File browser for digital assets

All component products support automation with Adobe Extendscript – a Javascript-like programming language. If you can describe an algorithm for a repeatable task, it’s likely you can automate it with Extendscript.

Like previous releases of the Adobe Technical Communication Suite, TCS4 provides full capabilities of the individual point products, with additional Suite-only integration features. Some of these features are somewhat trivial, like the ability to launch Adobe Illustrator or Adobe Captivate from a FrameMaker menu option. Some are quite substantial. Let’s focus on the “killer feature” of TCS4 – multiscreen HTML5 output.

Device Explosion in a Mobile World

Tablet and mobile computing has quickly gone from a niche use case to mainstream. It’s hard to believe that the Apple iPad was introduced little more than two years ago. But now millions of devices are in the hands of consumers and deployed by businesses. And today’s consumers expect readable, accessible content on any device.

The Solution? Multiscreen HTML5

The technology trio of HTML5, Javascript, and CSS3 were explicitly designed to support today’s World Wide Web, including the proliferation of devices.

Illustration showing text layout on desktop, tablet, and smart phone.Adobe’s multiscreen HTML5 output generates a set of HTML files for each target device. Javascript serves the appropriate set dynamically, in response to CSS3 media queries that test the pixel dimensions of the client device. If you publish to four device layouts (e.g., desktop, full-size tablet, mini-tablet, smartphone), you will have four sets of HTML files on your server. Since disk space is cheap, this isn’t a big deal. And RoboHelp will generate all sets of HTML concurrently. Browser detection will serve the appropriate set of HTML to your target device.

Responsive design purists may argue that Adobe’s multiscreen HTML5 output is not True responsive design. True responsive design would use a single set of CSS property definitions and a single collection of HTML files. CSS media queries test the target screen size, and specify formatting properties appropriately for that device. But true responsive design is very challenging to code, particularly for arbitrary technical content on arbitrary devices. I think the Adobe approach is valid.

How TCS4 Supports Multiscreen HTML5

RoboHelp 10 and Adobe Captivate 6 both provide the option of HTML5 output. TCS4 extends this capability across its component applications. With RoboHelp 10 as a publishing engine, either directly or indirectly (invoked from FrameMaker in what Adobe calls “Silent Publishing”), you can create and publish to rich, device-specific layouts. These devices-specific layouts accommodate the constraints of each device, and provide appropriate content formatting, layout, and navigation based on each devices’ screen dimensions.

Providing multiscreen HTML5 support in TCS4 was a brilliant move. Lots of technical content is locked away in legacy file formats. RoboHelp. FrameMaker. Microsoft Word. Not only binary file formats, but other formats those applications support, like XML. Multiscreen HTML5 support provides a relatively easy path for organizations to publish this content to mobile devices. Let’s discuss how it works.

Live-Linking in Adobe RoboHelp 10

In the TCS4 version of RoboHelp 10, projects can include linked FrameMaker and Microsoft Word documents. Project settings allow you to map FrameMaker and Word styles and other object properties to RoboHelp styles and properties when converting to online output. For example, FrameMaker cross-references may include page numbers, which you will want to suppress in online output. You can do this by remapping cross-reference format styles. Once you’ve done this configuration work, you can re-use these settings across multiple projects, and also access these settings for direct publishing from FrameMaker.

This configuration capability has been included in all versions of Adobe Technical Communication Suite, and the ability to publish directly from FrameMaker was added in TCS3. But with TCS4, you can choose multiscreen HTML5 as an output target, and automatically generate content in appropriate formats for a range of devices. TCS4 also supports ePub 2.01, ePub 3.0, and all other previously-available output formats, including WebHelp and Adobe AIR.

Configuring Multiscreen HTML5 Output

Before you publish to multiscreen HTML5, you must select or design screen layouts for the devices you want to support. RoboHelp 10 comes with several sample layouts. A link in the screen layout dialog promises to take you to Adobe.com for more layouts, although none were present there at the time of this review.

RoboHelp 10 also includes a screen layout editor, with widgets for screen areas like TOC, search, navigation, and content. If you have a good working knowledge of HTML5, CSS3, and Javascript, you can design your own screen layouts, using these widgets as a starting point.Adobe RoboHelp 10 Screen Layout Editor

When you configure multiscreen HTML5 output, you will select among available screen layouts for each category of devices you wish to support. The “out-of-the-box” HTML5 experience is pretty good. Sample layouts work well for common devices.

Native apps with PhoneGap

TCS4 goes further than HTML5. You may want to generate native mobile applications. These applications will meet some business cases better than HTML5 applications – they are locally installed, and can be distributed (for free or for a price) in the Google Apps Marketplace, Google Play Store, or Apple App Store.

To generate native applications, TCS4 uses PhoneGap, a solution that compiles HTML5 code into a native application. Adobe acquired PhoneGap in late 2011. PhoneGap will generate native applications for all of the currently-popular mobile operating systems, including iOS, Android, Windows 7, Blackberry, and even older operating systems like Symbian and WebOS. With some programming effort, you can also access capabilities of each device, like GPS/location awareness, screen orientation detection, and vibration/alerts, that are not directly accessible via HTML5.

TCS4 provides turnkey generation of Android apps. All you need to do is provide the location of your PhoneGap installation. For the iPad, iPhone, and other devices, you will need to invoke PhoneGap outside TCS4 to process your HTML5 output.

Android Emulator

Warning: Some application development experience is required to make this work successfully. If you don’t have any software development skills, mobile application development provides a great motivator to learn, and will add a valuable, marketable skill to your repertoire.

You can test your native applications on an iPhone or Android emulators. Again, development experience is required to set up and use these emulators. For live device testing, you might consider Adobe Shadow, which simplifies the process of previewing and testing on multiple devices.

Summary

Like any feature-rich software package, Adobe Technical Communication Suite 4 has warts. I’ve addressed some of the FrameMaker-specific issues in my FrameMaker 11 review. But the support for publishing new and legacy technical content to desktops, tablets, smartphones, and other mobile devices via multichannel HTML5 is well-done, and welcome in today’s increasingly mobile world.

A Look at Adobe FrameMaker 11

By Alan Houser

With the historic Adobe release cycle of 18-24 months for desktop software, the arrival of FrameMaker 11 in July 2012 should be no surprise. Let’s look at what the latest version of FrameMaker offers.

A Bit of Background on FrameMaker

Many people think of unstructured FrameMaker as the “classic” FrameMaker interface. Authors apply paragraph and character styles as they write. A combination of styles and page layouts (defined in a FrameMaker “template”) drive the document formatting. This is actually a very efficient way to author and publish technical documents that include complex tables, graphics, and cross-references, with consistent formatting and layout. Style-driven authoring also allows you to easily change the formatting and layout of publications — providing ease of publishing to multiple channels and devices.

It’s notable that FrameMaker was one of the first authoring and publishing tools to offer features for content reuse. Multi-file books. Variables. Conditional Text. These tools pre-date XML by at least several years. FrameMaker variables, in particular, are a powerful feature for replacing text strings (think “Product Name” or “Company Name”), that still does not have a direct equivalent in more recent document architectures like DITA.

Now, what’s new in FrameMaker 11?

Unstructured Features

New features available in unstructured FrameMaker include:

  • Automated Line Numbering – Yes, automatic line numbers.
  • Rapid Authoring with Quick Catalogs – Adobe’s term for a keyboard shortcut system, somewhat revised, that’s been in FrameMaker for many years. Unfortunately, the implementation of this feature is laggy, especially on first use.
  • Object Styles – Named styles for graphics. Globally update graphic properties by adjusting style definitions. A welcome feature.

FrameMaker 11 Object Style Designer

  • Hot Spots – A new graphic “hot spot” editor for defining hyperlink areas in a 2-D image.
  • 3D – Several features to extract data from 3D images to generate interactive documents. Automatically populate tables of parts, animations, and views, with hyperlinks back to the 3D image.

Unstructured Authoring Impressions

Clearly, the changes here are mildly evolutionary, not revolutionary. But that’s to be expected. The FrameMaker unstructured authoring paradigm has remained relatively unchanged for many years. Of the new features, I only consider “object styles” to be generally useful. Some of these will be highly useful to a segment of users (3D, hot spots, line numbers), but there’s nothing transformational here.

Structured Features

Let’s look at what Adobe has added to Structured FrameMaker:

  • Rapid authoring – Same as unstructured. Quick-access menus for element names. Same problem with lag.
  • Banner text – Pre-populate structured elements with “coaching” text; for example, “Type title here.”.
  • Smart paste – Paste unstructured content (e.g., Word, text) into FrameMaker. FrameMaker automatically applies structure.
  • Code View – A new alternative to FrameMaker’s traditional WYSIWYG authoring. View and edit XML source code.

FrameMaker 11 XML Code View

  • Author View – Another new alternative to FrameMaker’s traditional WYSIWYG authoring. Edit in a formatted view, but without text margins, running headers/footers, or page breaks.
  • XSLT/XPath 2.0 support – Select and run XSLT transformations on XML source content. Select portions of XML content by running XPath statements.

FrameMaker 11 XPath Builder

Structured FrameMaker Impressions

First, Adobe FrameMaker in structured mode remains among my favorite environments for authoring and editing XML documents (to be distinguished from XML configuration files, XML Schemas, XSLT stylesheets). The combination of document window, context-dependent element catalog, and structure view are easy to navigate and manipulate. I especially appreciate the structure view, which provides an appropriate amount of interactivity and real-time feedback.

What about structured authoring in FrameMaker 11?

Many of the structured features appear to be motivated by FrameMaker’s historic criticisms. To counter the notion that “FrameMaker is not a real XML editor” (a tired, old red herring), we have Code View. To counter the idea that WYSIWYG editing is not appropriate for XML authoring, we have Author View, which provides a lightly formatted author view without page breaks, very similar to the interface presented by most other XML authoring tools.

Other new features have been available in competing XML authoring tools for some time. Banner text and smart paste are available in XMetaL and oXygen. With XSLT/XPath 2.0 support and Code View, FrameMaker is now an authoring, publishing, and XML development tool. But dedicated XML development tools like oXygen are more feature-rich and mature as XML developer tools (and less expensive).

Why Upgrade?

There is one “killer feature” in FrameMaker 11, but it’s only available in Adobe Technical Communication Suite 4. That’s the ability to publish FrameMaker documents to tablet and mobile devices via multiscreen HTML5. Whether your FrameMaker source files are old or new; unstructured or structured, Adobe TCS4 opens a relatively easy path to multiscreen HTML5 publishing. Adobe TCS4 also opens a path to native applications for ios, Android, or other mobile operating system, through Adobe PhoneGap. This path lets you offer your document-based applications in the Google Apps Marketplace, Google Play Store, or Apple App Store, for sale or free.

Overall Experience

Sure, FrameMaker 11 adds new, welcome features. But the features are tacked on to an already over-loaded interface. Some of the new features are useful, but have a baffling implementation (for example, “Save DITAMap as FM Book with Components” uses seven templates). And many of the new features are already provided by other tools that do those particular tasks much better.

FrameMaker 11 Crash Dialog
FrameMaker 11 seems particularly “laggy” and “crashy”. I see the Microsoft Windows 7 “wait” cursor. A lot. Usually FrameMaker recovers. Sometimes it does not. Loyal FrameMaker users have come to expect this from new FrameMaker releases. Adobe releases buggy software, and cleans it up in auto-updated patches in the coming months.

What Adobe Should Do

Unstructured FrameMaker is a wonderful tool for authoring technical documents. FrameMaker’s style- and template-based paradigm provides “just enough” semantic markup for many organizations, with relatively low configuration costs (it’s not rocket science to create an unstructured FrameMaker template). When set up and used correctly, authors can create high-quality technical documents with a minimum of effort spent formatting. Organizations can publish documents with consistent formatting and branding to a variety of output devices.

Structured FrameMaker is a perfectly viable platform for XML authoring and publishing, whether against an industry-standard or custom-developed DTD. And structured FrameMaker is unequalled as PDF publishing engine for XML documents. No XML authoring and publishing tool is easy to configure, but the most common alternative for generating PDF from XML (XSL-FO) requires rocket-science level programming skills for customization.

But…with each FrameMaker release, FrameMaker becomes more difficult to use, and more challenging to teach (I’m an Adobe-certified FrameMaker instructor). The quirks of the interface abound. Click “edit variable”, and FrameMaker assumes you want to edit the _name_ of the variable. The conditional text pod is baffling – for me, an expert! The attribute editor dialog puts the “reset all” button in the location most dialogs reserve for “cancel”, so I find myself regularly zeroing out attribute values. Landmines abound, and I see FrameMaker users struggle more and more to use FrameMaker’s core features to create consistent, maintainable documents.

FrameMaker is still a wonderful authoring and publishing tool, with little competition in its core strengths. But the poor ease-of-use and complexity of the application are out of control. In future revisions, Adobe should consider focusing on the things FrameMaker does well, and make those things easier to do. Come on, Adobe. You can do better.

Rest in Peace, XHTML

Be liberal in what you accept, and conservative in what you send.

Postel’s Law (aka “Robustness Principle”), as phrased in IETF RFC 1122.

Once a fatal error is detected, however, the processor MUST NOT continue normal processing (i.e., it MUST NOT continue to pass character data and information about the document’s logical structure to the application in the normal way).

XML Recommendation, World Wide Web Consortium (W3C)

The first is a respected axiom of programming and messaging design. Web browsers have always adhered to this principle. While the tolerance of Web browsers has infuriated HTML purists and frustrated Web developers, that same tolerance has been directly responsible for the astonishing popularity of the World Wide Web.

The second is an intentional design decision by the W3C committee that created XML back in 1998. Known colloquially as “draconian error handling,” an application that parses XML (including, for example, a Web browser that validates XHTML markup), is required to cease processing when encountering an error condition in the XML markup. Abort. Full stop. Don’t even try to display the broken Web page.

If Tim Berners-Lee had specified the draconian error handling of XML when he first created the HTML language, the World Wide Web would not exist as we know it today. You would be aware of it, you would probably know people who use it; you would perhaps likely use it yourself. But it would not be the global resource with billions of pages of content, globally accessible on a variety of devices, and forming a major component of our daily lives.

The W3C has acknowledged that XML may not be appropriate as a distribution format. The W3C has ceased the activities of the XHTML Working Group, and has focused its efforts on HTML5.

Does this mean anything more generally for XML? I hope so. I believe there has become a general awareness in the XML community that draconian error handling may not be appropriate in many circumstances. XML processing applications, by definition, ignore the staid “robustness principle.” And it shows. XML processing applications with which I’ve worked are anything but robust. Quite brittle, in fact. And this is an ongoing problem for any organization that attempts to deploy XML-based publishing.

Leximation releases DITA-FMx 1.1

Leximation, Inc. has announced that the DITA-FMx 1.1 plug-in has been released. This plug-in improves upon the DITA support provided with Adobe FrameMaker 8 and FrameMaker9, including increased coverage of the DITA 1.1 specification and improvements to the authoring experience.

The DITA specification presents rather steep challenges to tool implementers. The Leximation plug-in further enhances FrameMaker as an option for DITA authoring and publishing. Given the complexities of XSL-FO for generating PDF output, and the recent uncertainty regarding PDF support in the DITA Open Toolkit, FrameMaker should be especially appealing for organizations that need high-quality PDF output from DITA.

Microsoft patch for infamous FrameMaker/PDF bug

Some users of FrameMaker on Windows XP and Vista (including myself) have been vexed by FrameMaker crashes while generating PDF files, and generated PDF files with missing text (not good). The problem appeared to be random, affecting some systems but not others, and some documents but not others.

The workaround (until now) has been to delete the file “C:WINDOWSsystem32FNTCACHE.DAT” and reboot. Many FrameMaker users would delete this file regularly, and some did so automatically through a shutdown script.

Mahesh Gupta, Product Manager for Adobe FrameMaker, reports that Microsoft has patched the underlying font management issues that have caused these problems. His post in the Adobe Technical Communication blog provides details of the Microsoft patch.

And there was much rejoicing among FrameMaker users!

Adventures in Beijing, Part II

In the late 1980′s, I had a work-study job as a computer operator in the School of Computer Science at Carnegie Mellon University (B.S.E.E. 1987, M.A. 1989). That meant keeping the systems operating and loading backup tapes. Lots of backup tapes. One of the projects I supported was a speech recognition effort led by a Carnegie Mellon PhD graduate and assistant professor named Kai-Fu Lee.

Shortly thereafter, I took a staff position there in the research documents group, which was tasked with telling the U.S. Government (primarily DARPA) what we accomplished by spending their money. Again, Dr. Kai-Fu Lee’s project was among those that I supported.

Twenty years later, I find myself in Beijing at the WWW2008 conference, in the audience at the opening keynote, delivered by Dr. Kai-Fu Lee (now Vice President of Engineering at Google). I think it says something about my career that I’m now half-way around the world, attending a keynote by Dr. Lee. Exactly what it says, I’m not sure.

Dr. Kai-Fu Lee at WWW2008

Adventures in Beijing

Last week I had the privilege of representing the Society for Technical Communication at the semi-annual meeting of the World Wide Web Consortium (W3C) Advisory Committee, this time in Beijing. As a W3C member, the STC participates in W3C governance. Perhaps more importantly, the STC can place members in W3C member-only roles, like participation in W3C working groups. There is substantial interest by the W3C in increasing the participation and support of the STC in its standards development and communication activities.

The W3C is working on standards in several important and exciting areas, including accessibility, mobile devices, the next generation of HTML, and the next generation of the Web itself, the Semantic Web. Leaders from each of these areas are interested in support for drafting specification documents (the W3C calls them Recommendations), and for writing and editing supporting documents to explain W3C Recommendations to appropriate audiences.

More on that later. Until then, a picture (me at the Great Wall, Mutianyu section):

Alan Houser at Great Wall

Events: Annual European Tour

I enjoy a journey to Europe once or twice a year, and this year is no exception. Over the next two weeks, I will be participating in several events:

  • The annual tekom/TCWorld conference takes place again in the beautiful German city of Wiesbaden, November 7-9. I will be presenting two sessions, Using DITA with FrameMaker, and Developing DITA Maps. This is my third visit to this conference.
  • I am privileged to visit Manchester England on November 10 and 11. I will be supporting the STC UK chapter wth a two-day workshop on DITA, DITA authoring tools, and the DITA Open Toolkit. Participants will have the opportunity to use two popular DITA authoring tools (FrameMaker and XMetaL), use the DITA Open Toolkit for publishing, and develop DITA specializations. Participants will receive a free copy of Mif2Go, a wonderful multi-purpose conversion utility for FrameMaker documents. Mif2Go has recently added unstructured FrameMaker-to-DITA conversion support.
  • November 13 – 14 brings me to Brussels for the annual DITA Europe conference. This is my first time at DITA Europe, but JoAnn Hackos always runs outstanding events. I will present on DITA Rapid Prototyping with the IBM Task Modeler. This is one of my favorite techniques with one of my favorite (and under-publicized) tools, the IBM Task Modeler.

Registration for each event is still open. If you are in Europe and are looking for a relatively low-cost training experience, I especially recommend the STC UK DITA workshop. As usual, I look forward to seeing many of my “virtual” colleagues in person at these events.

Adobe/Macromedia Synergy for Technical Communicators?

Adobe CS3 Master Edition Box I was originally skeptical of the Adobe/Macromedia merger. I saw another case of a larger company buying a smaller company purely to stifle competition, usually by killing those pesky competing products. Promises of greater synergy that usually pepper the press releases associated with these mergers are usually unfounded.

Not quite two years later, I’m a convert. I just received my copy of the Adobe Creative Suite 3, Master Collection. This package includes the key Adobe and former Macromedia products for image production, vector-based illustration, layout-intensive print production, Web content development, Flash authoring and production, as well as video and audio editing. Twelve major products in all, plus some ancillary goodies.

It’s notable that Adobe has chosen to maintain and improve Dreamweaver over GoLive. To call Dreamweaver a Web authoring tool is a massive understatement. Perhaps Web development environment is more appropriate. Dreamweaver was always a step or two (or three) ahead of GoLive in feature set and capabilities, and Adobe made the right choice here.

It’s all here — in on package, one installer. I suspect it’s not lost on the Adobe bean-counters that the cost of this suite is comparable to the cost of a computer with the required hardware to run it. Separately, however, the cost of these products would be several times that of the suite price.

I see similar synergy in Adobe’s technical communication products. FrameMaker for conventional and XML-based authoring and publishing, RoboHelp for online help development, Captivate for animations, tutorials, and simulations, and Acrobat for review, collaboration, approval, and distribution. Adobe can now cover a wide range of capabilities for technical communicators. And Adobe product managers are speaking of increasing cross-product integration. It will be interesting to see where this goes.

Adobe Technical Communication FAQ comes to Fruition

On July 23, Adobe announced the release of FrameMaker 8, which began to ship a week later. New features of FrameMaker 8 include Unicode, DITA, ability to embed “active” Flash and 3D objects in PDF, text-edit tracking, improved conditional text support, and attribute-based filtering. A review is available here.

In a first for Adobe, the company had provided some prior information about this release of FrameMaker. In the Adobe Technical Communication FAQ (PDF version), Adobe stated that “our [Adobe's] current assumption is that the next major release of FrameMaker will be in the first half of 2007.” Given the complexity of the FrameMaker application and of software development in general, missing this target by a month isn’t too shabby.

Adobe posted the Technical Communication FAQ in July 2006. This action was very highly unusual — Adobe usually holds plans for new product features and release plans in extreme secrecy. However, at that time Adobe was facing market skepticism over its revival of Robohelp, as well as lingering rumors about the future of FrameMaker. The Adobe FAQ, and Adobe’s execution of the plans it outlined, have helped to assuage this skepticism.

Technical communication tools development has been relatively stagnant for the past several years. These are exciting times for technical communicators, with renewed activity (and competition) in the tools development space. Let’s hope that Adobe (and other tools vendors) will continue to share some of their future plans with us.