Matthew Arnold Stern -- Writer and Speaker

WritersUA 2005 Trip Report, Or What Happens in Vegas Doesn't Necessarily Stay in Vegas

by Matthew Arnold Stern

Tropicana Hotel was the site of the WritersUA 2005 Conference In the six WritersUA (formerly WinWriters) conferences I've attended, there seem to be some consistent patterns. New technologies and trends are touted to be the solutions to all our documentation problems (but often aren't). Old technologies are supposed to die (but usually don't). After all, there are folks who still produce WinHelp.

This year's conference at the Tropicana in Las Vegas did reflect the economic recovery in our business. Attendance is up from the last time I was there in 2003, and a vendor had a drawing for a cool and expensive trinket, an iPod Mini. It's a far cry from the dot com days when the conference had 1,200 attendees and gave away a car, but it's reassuring to see the signs of recovery in our user assistance industry.

Here are my general impressions about the conference. I also have some follow up notes from my presentation.

RoboHelp is Dead. Long Live RoboHelp.

If you've been reading HATT and other Web sites for help developers, you probably already heard about Joe Welinske's statement about Macromedia putting RoboHelp on "sunset" and that the product will fall out of use in a couple years. (I'm sure Joe is probably tired of hearing about that quote by now.) It certainly didn't help that Macromedia didn't send anyone to the conference to refute him.

I have to admit some schadenfraude when I heard the news. I was a big ForeHelp fan, and was disappointed when RoboHelp pushed it out of the market. I've always hated the RoboHelp integrated HTML editor with all those stupid kadov tags.

But if Macromedia is indeed pulling the plug on the product, it's understandable. There really isn't any place for RoboHelp to go. If you are still producing WinHelp and HTML Help, any version from 2002 on will serve you well for years to come. WebHelp and FlashHelp have too much overhead and proprietary pieces for a Web-based help system. I'm doing my HTML-based help project with another fine Macromedia product, Dreamweaver MX 2004 along with Wrensoft Zoom Indexer to create a full-text search. I don't need to worry if a new version of RoboHelp would cause problems with my files.

RoboHelp may be joining ForeHelp in The Great Help Authoring Tool Collection in the Sky, but the creators of RoboHelp formed a new company, MadCap Software, They're busy on a new XML-based help authoring tool called Flare, which will be out later this year. It already has one feature I like, no kadov tags.

Content Must Be Separate from Format. I Repeat...

That was the official mantra of the conference, "Content must be separate from format. Content must be separate from format." It seemed like everyone said it. Even I said it in my session. Technical communicators are supposed to just focus on the content and its structure and let CSS, XML, XSLT, CMS, etc. handle the delivery.

This concept was treated like it were a revelation, but it really isn't anything new. If you use templates for your documents, you're already following that principle. Instead of applying FrameMaker tags, you'll apply XML tags. But if you think that technical communicators don't have to think about format, guess again. Who will wind up being responsible for developing the formats? We technical communicators will!

You can look back at history to know this. When desktop publishing first came out with tools like Interleaf and PageMaker, the mantra then was that layout was for designers and writers should just focus on writing (in whatever uncool, ungraphical DOS-based word processor management imposed on us). That was the case when I worked at AST. Then our management said, "Why are we wasting time having designers do the layout? The writers should do the layout – in Word!"

Yes, writers, you can (and should) focus on the content, but you will wind up having to worry about format. Expect to see more sessions about XSLT, creating XML schemas, and other things we're not supposed to worry about at future WritersUA conferences.

What Really Does Work in User Assistance

For me, the best session at the conference was William Horton's closing. He turned his entire presentation into a demonstration of interactivity. It started with everyone teaching each other how to make paper airplanes and then "[proving] that they work". (The last time I saw people try this in a learning environment, they were sent to the principal's office.)

He reminded us that today's videogame players will be tomorrow's enterprise application users. These are users who were born in the personal computer era, learned complex programs by figuring them out on their own, and whose most dexterous finger on their hand is not the index finger, but their thumb from texting and videogames. (In Japan, the nickname for teenager is "thumb tribe".) Will we expect them to learn by reading lengthy manuals or help screens? That's not the way my kids learned, because they started using computers before they learned how to read.

Instead, simulations will become an important part of user assistance. We would provide a limited mockup of our product (so that users can't expose or damage sensitive information) and enable them to experiment with it. The simulation would guide users and provide feedback when they make a mistake. We would provide users the opportunity to learn by doing.

Horton also talked about how storytelling could be used as a learning tool. As an example, he showed a Crimescene game that uses a mystery to teach users how to put together effective questions in an interview.

So, How Did Your Presentation Go?

I had the great fortune of speaking with 20–30 people who all knew about SDKs and were deeply interested in the subject. I got some excellent questions and participation from the group. In my demonstration, I invited a member of the audience, Bill Albing of Farpoint Technologies, to come up and enter source code comments into a Java project and see how they turn into Javadoc. (Bill is on the right in the following picture.)

I show Bill Albing (right) how to enter source code comments for Javadoc.

Bill later let me know about a great page on Wikipedia with information and a comparison chart of documentation generators. More info

As my volunteer, Bill received a free autographed copy of my novel Offline. (Want your own copy? Click here>>)

A copy of my supplemental information, which includes links to useful Web sites and instructions for replicating the demos on your system, is now available from the WritersUA Web site, or use the link under Downloads.

A couple of audience members asked questions that I promised to follow up on. Here they are:

Does CppDoc generate RTF files?

No. CppDoc just outputs to HTML.

What happens to links to external HTML files when you generate the Javadoc in a print format (i.e. FrameMaker)?

According to Sun's documentation for the MIF doclet, HTML hypertext links are converted into static text followed by the URL in parentheses. These won't be live links, but the reader will know where to find the information. (More info) The external document is not converted to MIF.

But in the sample I demonstrated in the session, the URL didn't appear:

If you specify a relative path in the source code comments, the URL does not appear in the generated MIF file.

The problem was that I used a relative path in my hypertext link (shown in red for emphasis):

/**

* Gets the word at a given index in its scrambled form.

* For testing purposes, refer to the <a href="wordlist.html" 
target="_blank">list of scrambled words</a>

* provided with the Javadoc.

* @param idx index of required word

* @return word at that index in its scrambled form

*/

If you make the link an absolute path, the link appears in the document correctly.

If you use an absolute path, it appears in parentheses after the text in the generated MIF file.

There is an option, hrefdocroot, you can use during Javadoc generation that supposedly provides an absolute path for relative links. (More info) I haven't been able to make the option work on my sample. It may be because I didn't put the link in an overview.html file. I will research further, but I'm sure that using an absolute path in the hypertext link in the Javadoc comments will work.

How to do you keep FrameMaker from checking for updates when you're not on the Internet, which can crash your system?

Actually, this is my question. FrameMaker did this to me in the middle of my demo. (We all know that you can't have a demo without at least one technical glitch.) Fortunately, audience member Martha Kolman-Davidson suggested that the online update feature can be turned off. To do it, select File | Preferences | Adobe Online. In the Adobe Online Preferences window that appears, select Never for "Check for updates".

You Can Only Reinvent Yourself So Much

The user assistance industry is a lot like Las Vegas. It keeps reinventing itself, but it still remains the same.

It was a point that was made clear to me when I visited The Casino Hall of Fame in the Tropicana. Part of the exhibit showed the demolition of old casinos on the Strip, such as the Landmark, the legendary Sands, and the Hacienda. Such implosions have become Las Vegas events and have appeared in movies and as the grand finale of a New Year's eve celebration. Even the Tropicana where we met is rumored to be next for the dynamite and nitroglycerine, so it's good that I left when I did. But even with all the old casinos falling and new ones taking their place, Vegas is still a place to lose money and gain weight.

The user assistance industry is filled with our Landmarks, Sands, and Haciendas, but we still have the same challenge: How do we teach users to use these complex products we're supposed to document? The tools and technologies may change (or not), but not our mission to teach our customers how to use our products successfully.