A few months ago, a particular reply in a long-running Techwhirler mailing list discussion on minimalism and Information Mapping in documentation caught my attention. The original post covered, in almost chronological order, the development of the ideas and discussions that are so popular in DITA, single-sourcing, and content reuse.

The original discussion cites practically all the popular technical communication textbooks and references we read today, from JoAnn Hackos to Ruth Clark, Gretchen Hargis, Ann Rockley and Kurt Ament.

Evolution of “minimalism, Nurnberg funnels and DITA”

I’ll just reproduce part of the original post by Bob Doyle (creator of the first DTP program, MacPublisher, 1984) that caught my eye. The original post has all the useful hyperlinks in place. It’s well linked and referenced, and I highly recommend the reading the original:

The historian of technical communications, R. John Brockmann, researched efforts to document products going back centuries. He finds that some of today’s hottest new documentation ideas were present in the work of those creating, documenting, and selling the technology of manufacturing just after the revolutionary war.

Today’s computers, with their spectacular graphical interfaces, allow us to present animated visual images, even 3-D models to illustrate complex machinery. But this is not the work of the everyday tech writer. Flash animations and computer-aided design (CAD) demand skills more like those found in a game design team than a lone tech writer and wordsmith.

Reading this inspired me to investigate some of the tools and origins on Wikipedia. The following is what turned up in my search.

Evolution of tools that let you publish lengthy, complex documents

1981: Quicksilver or Interleaf by Broadvision

“A competitor of the Adobe FrameMaker product. Broadvision acquired Interleaf in January 2000 … still in use in many companies worldwide. “

1986: Ventura

“The first popular desktop publishing package for IBM PC” … developed at the legendary labs of Xerox Parc in 1986. Originally known as Ventura Publisher. Acquired by Corel Corp (owners of PaintShop Pro and Draw!).

1986: FrameMaker

“Adobe FrameMaker is a desktop publishing (DTP) and word processing application that is popular for large documents … Designed by an extraordinary mathematician … an extraordinary product for its day, enabling authors to produce highly structured documents with relative ease … attempts to sell to home DTP was a disaster … did not feature multiple undo until version 7.2″

1987: Quark Xpress by Quark

“A computer application for creating and editing complex page layouts…The first version of QuarkXPress was released in 1987 for the Macintosh… 1992 for PC.” Single-sourcing is called the Quark Dynamic Publishing Architecture.

2006: Blaze by MadCap Software

In development.

How are these products doing and viewed today?

Most of these products still exist today in various versions. What does 20-year-old software look like? Do they look anything like their originals? Fast forwarding to today, let’s take a look at a few quick snapshots from the Internet.

Turning over a new leaf at Quark

“Criticised heavily in recent times for selling what some believe to be an overpriced and outdated product with a lack of customer support, Quark is at pains to affirm that it has finally got its house in order.” (See “Turning over a new leaf at Quark.”)

Note: For some reason, the original comments posted by readers on the post above appear to have been filtered out. It was the original fiery readers’ comments in relation to the news article above that made this link so memorable to me even after all this time … a bit like the monkeyPi post.

A Modest Proposal for Reviving Ventura Publisher

The community speaks out on a need to revive Corel Ventura. You can still find Corel Ventura for a bargain on the Corel site — very 90s.

FrameMaker rebundled, updated, petitions for Macs

New features and fixes have been added to FrameMaker 8 in recent months, including fixes, new features and bundlings for a Tech Comms suite. There are also petitions from a very vocal community base …

• Adobe and FrameMaker (dated , written in 2005).
• Petition for Adobe to develop FrameMaker for Mac OS X

Summary

A fair number of these tools have roots that go back to the 1980s. For example, Interleaf and its Technical Publishing System got its start in 1981.

SGML and the work of Charles Goldfarb and others started the foundations that would then lead to XML, which is the foundation today in modern desktop publishing and help publishing tools from Flare, Blaze, AuthorIT, etc.

This post was simply a journey into the past, a curiosity to examine the foundations and evolution of tools and thoughts that led us to the new generation of tools, XHTML and CSS standards that we rely on today. For every conditional tag, hyperlink and cross-reference you use, glyph, or PDF document you create, remember the pioneers.

Still, the tools of today have new challenges that must go beyond print or big complex books. Publishing to compliant online formats is important, as is built-in search, web commenting and expectations on user participation. An exciting time … indeed.

About Daniel Ng

Daniel Ng, a technical writer/trainer/knowledge manager of four years, is passionate about technical writing, and is a converted MadCap Flare and Lingo user in Malaysia. He occasionally spends weekends conducting 15 minute Creative PowerPoint sessions for youth at his local church in Batu Pahat.

Tom’s Post Commentary

Daniel, thanks for posting. I’m too young (32) to have gone through the days of Corel Ventura and Interleaf, but I asked an older colleague today if he’d heard of them. “Oh yes, I used to use Corel Ventura,” he said. “It was like writing with an early version of Framemaker and a brick in your mouth. You had to specify everything in picas.”

Daniel’s historical tour of products raises an important question that never has a clear answer: Why do some tools succeed and others die?

“Marketing,” my colleague replied. And then we talked about Word versus WordPerfect.

I had an online chat with another technical writer today and asked him the same question — why do some tools succeed and others die? His reply:

I don’t know if you could call it a “quality,” but in this business it seems that first to market and most widely distributed is the major key to success. Obviously, as a tech writer, I recognize that usability plays a major part, but most businesses don’t seem to get that.

For example, I asked an employee at a local electronics store why I could not purchase a DVR that his store used to carry. I wanted to dump my VCR for a hard drive, and I don’t want to sign up for some service. The employee responded that too many of the DVR units were returned by users who could not use them. Therefore, the store is no longer selling this product.

Parenthetically, those large corporations selling the services have paid off retail chains to sell the services, not the DVR units. Did anyone learn anything from that (lack of usability)? I doubt it. The most definitive quote I heard a few years ago was allegedly uttered by a business owner who said, “ Why should I pay to provide customers with documentation? I already have their money.” Apparently, repeat business was not an issue, as this business owner opined that he would be long retired before he ran out of first time customers.

Now we’re up to three answers: marketing, first in market, and perhaps usability. I would also add community to this list. Without a strong community of users, a product tends to wane. Even bad products can continue successfully if the user community is vibrant. Think Twitter.

A few months ago, I listened to a Quark presentation at Doc Train 2008. I didn’t even know Quark was still a player, and yet their name appeared on all the conference bags. The presenter was explaining how through XML you could single source your documentation, or something like that. Is it too late for these old timers to get back in the game? Will tools always be in a constant state of flux, changing every 5 years?

Perhaps. I guess the point is not to be too invested in any tool. Learn the underlying technologies (e.g., CSS, XML, HTML) that the tool uses. If one day the tool you’re using doesn’t meet your needs, there are at least 20 more to choose from.

Finally, sometimes tools succeed or fail based on unpredictable conditions and factors. Scott Berkun’s The Myths of Innovation explores why some ideas ignite and others don’t. Often it has everything to do with timing. Sometimes the conditions are right, the users are there, and the need is paramount. Other times it’s like launching a sailboat on a windless day.

For more information on tools, see the WritersUA list of tool resources. You can also see the Help Authoring Tools Matrix.

By the way, I have a small, informal tools survey in my sidebar (which is hardly representative of the great number of tools out there). But if you feel like participating, go for it.

This past month I’ve been heavily using the RoboHelp 7 and Captivate 3 components of the Technical Communication Suite. RoboHelp 7 offers some impressive new features: snippets, breadcrumbs, a pod-based interface that you can drag around, integration with Framemaker and Captivate, and so on. But as is the case with many new releases, there are some bugs and unexpected shortcomings.

Captivate Integration Led to Fuzzy Videos

I really love the integration with Captivate, and the inclusion of Captivate is what sold me on the product. RoboHelp 7 allows you to begin Captivate movies from within RoboHelp. That way you don’t have to keep re-importing the files each time you update them. Additionally, you can directly embed screen demos on topics or in drop-down hotspots.

I think that’s the strength of the product, and for the most part it works well. But some glitch happened in RoboHelp that resized my Captivate movies and made them look fuzzy. I ended up deleting the RoboHelp-initiated movies and imported them manually instead (File > Import).

Firefox Display Never Finishes Loading

I was disappointed to see that my custom webhelp skin wouldn’t work in Firefox. It loaded eternally and kept trying to load until I pressed the Escape key. The Back and Forward buttons don’t store any history (until you press Escape). So when you do finally click Back, it takes you out of the help. Click Forward and it takes you back into the help, but with no TOC pane.

Luckily, there is an easy fix for this. It only involves a quick change to some lines of code. Go to Peter Grainge’s site and see the section “Help is slow to complete loading or it fails to complete loading.”

Bullets and Sub-Lists Display Differently in Firefox

While you’re looking at your project in Firefox, you might want to look closely at your bullets and sub-lists (by sub-list, I mean a, b, c …). If you apply a style to either of these elements, Firefox’s display looks goofy. The bullet or sub-list is left-aligned, while the text is spaced too far to the right.

You might also want to be careful about manually editing the css style sheet. I opened up the css style sheet in Dreamweaver and edited the topics while keeping the RoboHelp project open. It was cool to bypass the tedious style editor and quickly modify my styles like this. However, when I published the file, the output in Firefox was skewampus. In addition to the bullets and sub-lists problem, paragraph spacing was absent. Plus the help’s buttons didn’t work and the TOC collapsed on a Kubuntu OS.

I recommend using RoboHelp’s official style editor, and perhaps playing with the _ns.css stylesheet that RoboHelp outputs when you generate help.

Easy to Drag Panes into Oblivion

The new graphic interface with the draggable panes looks more modern, and you can actually drag the panes onto other monitors. But be careful with this. If you have popup windows that open on a second monitor, when you switch back to single monitor mode, RoboHelp might not know you’re only using monitor. I had an Import dialog box that kept opening on a second monitor that I didn’t have, and the app would freeze until I hit escape to close the invisible dialog box.

When I switched back to dual-monitor mode, I dragged the Import box where it should appear, and that fixed it.

Webhelp Skin Graphics Lacking

I really wish Adobe would have created more appealing webhelp skins. I think they added one new skin (“Beautiful Vista”), but it’s not very beautiful. If Adobe hired more graphic designers to create up-to-date looking buttons, the output could be a lot more attractive.

Online Help Quality Plummets

RoboHelp’s online help is interesting. There’s an online and offline mode. (The online mode didn’t work at first, but they eventually fixed it.) In Rob Houser’s review, he noted how the help was careless and sloppy. I’d add the word “uninformative.” It seems to lack more comprehensive instructions specific to the Suite.  The help points out the obvious in too many places, without providing real insight.

Rob writes,

I hate to make this observation, but RoboHelp’s online help seems to be getting worse. I’m not talking about RoboHelp’s ability to output a professional and standard looking help viewer. I’m talking about the help content that is supposed to help you learn and use RoboHelp. The examples may not seem dramatic, but taken as a whole I’m afraid that new users may not be able to learn RoboHelp simply by using the online help. They certainly aren’t seeing best practices and full RoboHelp capabilities being demonstrated.

For example, I wanted more thorough instructions on how each component interrelates with the others. When you initiate a Captivate movie from within RoboHelp, the source file (with a .cp extension) remains in your computer’s My Documents > My Adobe Captivate Projects folder — which is outside the RoboHelp project folder. To edit the movie, you right-click the .skn file from inside RoboHelp’s interface (in the Project folder) and that skin file opens the .cp file on your desktop. Don’t rename the .cp file or the .skn file won’t recognize it.

Also, don’t manually delete anything from the RoboHelp project folder (such as through Windows Explorer) because doing so will corrupt the .cpd file and RoboHelp will have to re-index the contents of that folder. I wanted more information like that in the help.

Framemaker Import Groundbreaking But Irrelevant for Me

Although the integration with Framemaker is revolutionary, I’d still rather output to a Frame file, rather than import it. Rob makes some noteworthy comments about this interaction:

The import is only one way—from FrameMaker to RoboHelp. However, many RoboHelp features are not supported in FrameMaker documents, so single-sourcing from FrameMaker to RoboHelp would seriously restrict the quality of your help system.

Another big issue: there is no capability for generating the printed documentation from RoboHelp in FrameMaker. This means the main form of printed documentation supported by RoboHelp is still Microsoft Word, which has numerous layout and formatting issues that have not been addressed for over seven years.

In his conclusion, he makes an interesting observation comparing Robohelp to Flare in terms of Framemaker interaction:

Flare is developed by a team that is experienced with help authoring, and—perhaps the most confusing distinction—Flare seems to support FrameMaker more thoroughly both for importing and exporting content than does RoboHelp.

Conclusion

RoboHelp continues to ignore some major issues, such as the lack of character-level indexing and the formatting errors when you export to Word. Despite my complaints, I like many others have an affinity for the usability of this tool. It’s like an old pair of sneakers that has some new laces and polish. Maybe some new traction too.

I’ve especially been playing with the Captivate-RoboHelp integration. So far I think it’s pretty amazing. You can embed Captivate movies directly in your online help, even in drop-down hotspots. For example, you can have a drop-down hotspot link that says “Show Me.” When the user clicks it, rather than opening up a new window, the show me demo drops down and immediately begins to play the demo.

You can either begin Captivate projects directly from RoboHelp, or insert the demo from an external Captivate file. (If you insert the swf file from an external file, be sure to choose the swf file that has the word Skin in its name so that the border and player controls are also inserted). With Acrobat 3D, you can even embed Captivate movies within PDF documents.

If you’re trying to learn Captivate, by the way, check out the tutorials by Andrew Brown here: http://www.swict.com/captivatecourse.asp. Brown’s tutorials are both helpful and a good model of how tutorials should be.

If you’re a Framemaker user, RoboHelp has some stunning integration with Frame, but I haven’t explored that yet. I’m mostly interested in online help coupled with Captivate tutorials.

For the podcast, I’ll be doing some upcoming shows on Adobe products. They have quite an amazing lineup, and are now packaging their products together in suites (for example, see the Creative Suite).