Adobe AIR

Since Adobe introduced AIR, there’s been a lot of discussion about what it is and why to use it. I’ve also been asked how it applies to RoboHelp specifically. The Adobe web site describes AIR, but I think the discussion is aimed a bit too much at developers and not enough at RoboHelp authors, so here’s my short initial take on what AIR is in general and for RoboHelp specifically.

In general…

AIR, Adobe Integrated Runtime, is an output format with characteristics of both web-based and desktop applications. It’s web-aware but doesn’t run in a browser. Instead, it runs like a desktop application, which lets it take advantage of desktop features like local file storage. Yet because it’s web-aware, it can search the web for updates if users have an internet connection and update itself as needed. Adobe has stated that it plans to implement AIR across its product line, essentially creating a new output format.

For RoboHelp…

The Microsoft HTML Help output format (CHM) is an old (pre-‘97) and increasingly constrained format that looks increasingly antiquated in an increasingly webby world. It will be around for a long time, just as WinHelp has been around since it was unofficially put to sleep in ‘97, but I consider it a dying format.

However, HTML Help has one great attribute – it’s compiled. No matter whether a project contains one topic or a thousand, they’ll all be encapsulated into one distributable CHM file. IT managers like this because they only have to distribute one file. That one-file model is increasingly out of place in a web-oriented world, but its simplicity is a virtue.

In contrast, WebHelp, created by eHelp (original vendor of RoboHelp) in ‘97/’98, is not compiled. If a project contains a thousand topics, you have to distribute one thousand files – slightly more counting the control files. (This sounds difficult but it’s easy since RoboHelp puts all the files in one WebHelp folder. You just distribute that folder.) This makes WebHelp more efficient for web-based distribution because it acts like a web site. If users call for one topic, they get that one topic rather than all one thousand as they would with the CHM. However, IT managers often don’t like having to upload those thousand-plus files to a server.

The RoboHelp Packager for Adobe AIR tries to get the best of both formats. (To download beta 2, see http://labs.adobe.com/technologies/robohelp/.)

Like HTML Help, the Packager encapsulates all the distributable files in one AIR file. This means IT only has to deal with one file rather than hundreds or thousands as it does with WebHelp. (Even though those files are contained in a single WebHelp folder, they still have to be distributed.) For many IT managers, that’s a big benefit by itself.

Once you output to AIR, you get several other options as well.

You can apply skins, a la WebHelp. However, the skins are more flexible. For example, you can add a Resources button on the toolbar with links to other web pages. If you select one of those links, the target page opens in the AIR window in its own tab. This lets users keep the help file and other web pages open at the same time and access them quickly by just selecting the desired tab.

The output should look consistent on different platforms and operating systems. (I’d want to see a greater base of experience about this before accepting the idea wholeheartedly since different platforms and operating systems often have odd twists. However, since the output is not running in a browser, the browser display differences that we often see shouldn’t be an issue.

You can give users the ability to comment on the output, lending a Web 2.0 air to RoboHelp for the first time.

What do we have to do to make AIR work on users’ PCs? According to the AIR help, users must have the Adobe AIR runtime environment installed on their PCs. This seems like a straightforward download and installation. However, compared to the simple Flash Viewer installation procedure that many users are accustomed to, the AIR runtime installation is going to look more difficult and may slow acceptance of AIR until the runtime installation gets simpler.

I’ll add more as the RoboHelp Packager for Adobe AIR firms up.

Microformats

In April, I gave a workshop for the Boston STC on the issue of doing structured authoring without using DITA or Frame. In the workshop, I happened to mention a technology called microformats which several people asked me to define during and after the workshop. I did but, in retrospect, decided that I wasn't satisfied with the answer that I gave. So, here's a better definition that also has a number of additional ramifications.

Microformats use elements from existing languages or standards, like HTML, to mark up web content in such a way as to add semantic information to that content for use in Web 2.0, without having to adopt new languages or standards. Basically, microformats re-use existing features of current languages and standards.

There are several issues tied up in this definition. Let's take a look at two big ones.

- Existing languages or standards... - Every language or standard has a number of widely-used features and an often much larger number of little-known features. The latter often go unused or unnoticed. For example, the rel attribute of the link tag points to the location of the CSS that we attach to a topic in a help system, but rel often goes unnoticed unless you delve into the code. Yet rel is actually pretty flexible, offering a bunch of pre-defined values *and* the ability to define your own. This can get pretty esoteric, but it does not require you to buy and learn new software, just new ways to work what you already have.

- Semantic... - HTML tags like h1 are presentational rather than semantic. In other words, applying h1 to text tells us how to display that text but not what it is. For example, consider an online book store that uses HTML to mark up its listings. We could create a book listing and use h1 for the book title and h2 for the name of the author. We can then format the display by specifying the style attributes for h1 and h2, but we have no way of knowing that h1 is actually the book title and h2 is the author's name - e.g. the semantics of the information. XML lets us fix this by creating our own, semantically-definitive tags, such as creating and using tags called and rather than h1 and h2. But HTML already has elements that carry semantic information, such as the "cite" element that lets us identify a block of text as a citation. In other words, we may well be able to add semantic information without having to move to XML or DITA.

For a detailed overview of microformats, I recommend Microformats: Empowering Your Markup for Web 2.0 by John Allsopp, published by friendsof. In fact, I recommend reading the book even if you never plan to use microformats because of two other useful aspects of the book.

The first is the author's discussion of structural and semantic HTML in chapter 3. Here, he discusses some of the more rigorous programmatic aspects of HTML, how they're implemented, and why they're important for the long run.

The second is the nuggets sprinkled throughout the book, such as this one on why XML is important for RSS feeds.

"...RSSs are also XML-based languages, meaning that feeds must at least be well-formed..."

(from Microformats: Empowering Your Markup for Web 2.0, page 226.)

Why does this matter for technical communication? Today, most material produced by technical communicators is self-contained - e.g. a help system or user manual produced by one developer. But the web already has features like RSS feeds and aggregators that may be just as useful for technical communication. What the nugget above is saying is that RSS feeds and aggregators will most likely require XML, which will require a move away from HTML and the adoption of authoring tools that produce content that's at least well-formed if not valid. ("well-formed" and "valid" in the programmatic sense of following XML syntax rules.)

The book assumes familiarity with HTML, XML, IETF, and other acronyms and is very dense, but it's a quick read if you just look at a few code samples to get the idea and focus instead on the larger issues of programmatic rigor. Highly recommended.

How We Got Here - A History of DITA (and other things that we see today, not necessarily DITA-related)

Technical communication tends to focus either on the present (gotta finish the project...) or on the future (what's the next big thing and how might it affect me). The past sometimes gets lost. Yet if we get beyond the "When I was your age..." stories, the past can often teach us a lot - why did a particular technology or tool or methodology fail ten years ago, for example - letting us draw parallels to something we're doing today. And if nothing else, the past is intellectually interesting. How did we get to where we are today...

On that note, I recommend reading a history of DITA, written by long-time DITA consultant (among many other things) Bob Doyle. The article, available at http://dita.xml.org/book/history-of-dita describes the history of DITA but, in a larger sense, describes the evolution of today's technical communication field. Highly recommended.

If You Plan To Attend My Captivate or RoboHelp Workshops at DocTrain West...

Please follow these setup instructions.

For the Captivate 3 workshop:

Please install and test at least two working days before the workshop.

Hardware:

· Intel® Pentium 4, Intel Centrino®, Intel Xeon®, or Intel Core™ Duo (or compatible) processor
· Microsoft® Windows XP with Service Pack 2, Windows 2000 with Service Pack 2, or Windows Vista™ Home Premium, Business, Ultimate, or Enterprise (certified for 32-bit editions)
· 512 MB of RAM (1GB recommended)
· 700 MB of available hard-disk space after installation
· CD/DVD or USB drive
· 800 X 600 screen resolution (1024 x 768 recommended)

Software:

· Microsoft IE 6 or later
· Adobe Flash® Player 7 or later
· Captivate 3. To download a trial copy, go to www.adobe.com/products/captivate/, click the Download Free Trial link, and follow the instructions on the screen. The trial version is not supported on Windows 2000.

If you have any problems, please contact me immediately.

For the RoboHelp 7 workshop:

Please install and test at least two working days before the workshop.

· Pentium III 300 MHz or above.
· 256 MB RAM or more.
· 400 MB disk space or more.
· Windows 2000 SP 4 or later, preferably XP.
· Word 2000, XP, or 2003.
· IE 6 and any other browser that you support.
· Adobe Flash® Player 7 or later.
· CD/DVD or USB drive.
· RoboHelp 7. To download a trial copy, go to www.adobe.com/products/robohelp/ and follow the setup instructions. Accept all defaults to install RoboHelp. You do not have to install RoboPDF or RoboSource Control unless you want to try them after the workshop.

If you have any problems, please contact me immediately.

Unusual Uses for Captivate et al

Visual help authoring tools like Captivate, Camtasia, and Mimic were initially designed for creating software-related “movies” showing how to use features or perform tasks in a piece of software. They’re great tools – easy to use, cheap enough (most in the $299 to $699 range) that they pose a real threat to “big” tools like Authorware and Toolbook, and flexible. That flexibility is one of the best features because it leads authors to use these tools in ways that the vendors perhaps never intended, or even thought of. For example:

Role-playing simulations – The tools make it easy to create role-playing sims like sales or HR training. Captivate 2 came with a sample that tested your skills as an automobile sales rep, and Captivate 3 comes with one that teaches interviewing skills. But these sims can cover almost any topic; in 2007, I created a sim that showed how to determine whether a baby’s diaper needed to be changed. (With apologies to my grand-niece Eleanor Ruby, aka Ellie Belly.)

Games – Your first response to the idea of using these tools to create games may be no. That was mine, until I realized that it simply depends on how you define “game”. In some ways, interactive role-playing or software sims are games – the difference lies largely in the tone. And these tools make it easy to create scorable “games.”

Comics – In early ‘07, an attendee in my Captivate class asked what I thought of the idea of using the tool to create anime-style comics. I was going to say that it didn’t seem appropriate until I remembered the evolution of my thoughts about using Captivate to create games. Depending on what you want to do, I see no reason why not to use these tools to create anime, or other types of comics.

One serendipitous thought about where to get graphics for your animated comics. Silke Fleischer, Adobe’s product manager for Captivate, mentioned in her blog (http://blogs.adobe.com/silke.fleischer/) the idea of creating a Second Life (http://secondlife.com/) account and capturing the characters. This may be a lot of work initially if you can’t find someone who’s already using Second Life, but once you learn the software and create character(s), you effectively have your own animation studio.

Usability test recording – Less odd but more useful, these tools let you create your own usability test recording tools. One of the problems that I often hear regarding usability testing is the cost of the testing facility in general and tools in particular. In response to one question, I figured out how to use Captivate as a tool to record the results of software usability tests. It’s not perfect, but it does do a surprisingly good job. I write a tools column for the IEEE/PCS (http://ewh.ieee.org/soc/pcs/) and, in November, 2006, wrote a column on that topic. I won’t repeat the details here, but I’ll be happy to send a copy of the column if you’re interested. If so, contact me at nperlin@nperlin.cnc.net.

iSommelier - Extreme Single Sourcing

There's a lot of talk in technical communication about single sourcing, to put it mildly, but how does single sourcing actually manifest itself?

If we focus on online outputs, we're typically talking about one help file designed for use on a large-screen device like a desktop or laptop PC. Occasionally, someone will output in multiple formats, such as WebHelp and HTML Help, but still for a desktop or laptop PC. Rarely, someone might have to output for handhelds or, rarer still, to voice, ink, or other unusual systems.

One common denominator behind all of these outputs is individual interactions and standard units of content - one person at a time using one topic at a time. But a recent article in Business Week (The iSommelier Will Take Your Order, Feb. 25, 2008, page 72) introduced a new and unusual type of output.

iSommelier is a wine bar with a touch-sensitive surface, like an iPhone and on the same lines as Microsoft's Surface (see http://www.microsoft.com/surface/). The idea behind iSommelier is that guests can review a restaurant's wine selections, read tasting notes, and place orders using their fingers as navigation tools on the device's surface. As the writer describes it:

"... a list of countries materializes. I choose Spain. Then a menu of regions appears, and beneath that, a selection of wines. I drill down some more, and a graphic displays details about the producer and grapes, along with tasting notes arranged in a rosette pattern..."

Touch-screen computers aren't new. ATMs have been around for years. But interfaces like iSommelier offer more interesting displays and group interactivity. It's also an excellent illustration of how unexpected technical and marketing forces may affect how we create and structure content for display in unexpected venues. Imagine that you're the content developer for a wine reference web site and are told by the sales manager that the company just won a bid to provide information for some weird new product called iSommelier... Some possible effects:

- In order to avoid writing content multiple times, you'll have to be able to repurpose your existing content for iSommelier and whatever comes after that.

- The need to manipulate the content means it'll have to be coded using proper syntax. This could drive your move toward XML, since you'll need clean code in order to be able to repurpose the content quickly and automatically.

- The need to manipulate the content also means it must be structured consistently. The obvious answer is structured authoring, but according to what standard? DITA is often presented as the answer to all structured authoring needs but, from what I've seen of it, it lacks the flexibility to handle something this unusual. (I'm open to correction from other DITA users here...)

One argument against worrying about products like iSommelier or technologies like touch-surface driven interfaces is scarcity and price. iSommelier costs $250,000 and Microsoft's Surface is expected to cost $5,000 to $10,000 per unit, limiting their market penetration. True, but notice that Surface is already over 95% cheaper than iSommelier and costs will continue to fall if there proves to be a market for this kind of technology. (The first laser printer I ever saw was the size of a desk and cost about $250,000. My latest is a color laser with automatic two-sided printing that cost $399.)

Without trying to read too much into one interesting but niche product, iSommelier is a harbinger of the types of uses for our content that may show up out of the blue, and that we can only be prepared for by following standards.

Return of RoboSource?

If you used RoboHelp in the X5 days, you may have noticed RoboSource Control - the free version control system that shipped with RoboHelp. It was so simple that many people who saw it had the same initial reaction - "a toy version control system." But that reaction was wrong. RoboSource made version control simple enough that it didn't take your focus away from the actual project work.

Unfortunately, RoboSource 1 had problems. One bug corrupted a RoboHelp project if you added it to version control through RoboSource, but you could add the same project to version control just fine through RoboHelp. There was also a limit to how many files RoboSource could handle. A rule of thumb was to expect problems if a project neared the 2,000 file mark and to be surprised if you didn't get problems above 2,000 files. (2,000 seems like a lot, but consider a 1,000 topic project plus screen shots and you'll see that files add up quickly.) Finally, the documentation wasn't clear, so many people never tried it because they didn't understand how it worked in the first place. And RoboSource just dropped out of sight during RoboHelp's time in limbo under MacroMedia.

When Adobe released RoboHelp 6, one feature that was lost in the uproar was a new version 3 of RoboSource. (Adobe kept RoboSource 3 when it released RoboHelp 7.) I ignored it until three client calls in the space of a month made me go back and look at it again. And helping one client implement it exposed me to some of the internals of the new version and some of its peculiarities.

At a high level, RoboSource 3 works the same way as v. 1. Create the RoboHelp project, then add it to version control. Once you do, there's one other step that has to be performed once. The first time you open a project after adding it to version control, you do so by opening it specifically from the version control system. This creates a local copy of the project on your C drive. From then on, you open the project locally, like you would if the project wasn't in version control. When you do, RoboSource compares the versions of each file in the version control system on the server to the corresponding file on your C drive. If the local version is newer, RoboHelp uses that version. If the server version is newer, RoboSource copies it to the C drive and opens it in RoboHelp. In other words, you're always working on the local version which is being kept up-to-date by RoboSource.

Once the project is in version control, you get the expected check-in and check-out features, along with rollbacks and "diffing" - e.g. "differencing" or comparison of two versions of the same file.

RoboSource 3 still has peculiarities, the biggest apparently still being its file capacity. According to tech support, RoboSource 3 is based on SQL Express so, in theory, its capacity should essentially be unlimited. In practice, however, a client in Florida tried to load a 4,000 topic RoboHelp project (closer to 5,000 files when you count the graphics and control files) only to have RoboSource hang, apparently. This happened late enough in the afternoon that he decided to go home and clean off the server in the morning. But when he arrived the next morning, he found that the project had been added to version control. RoboSource had just gotten tied up with some function the previous afternoon and didn't provide any status messages to that effect, so we thought it had crashed.

In summary, RoboSource 3 is worth a look if you need a cheap and simple version control system. (Do not use the original version, even though it's still available in the RoboHelp 7 toolbox pod.) Try a few small and simple test projects first to see if it's working correctly and, if it is, give it a shot. And let me know what happens...