Hyper/Word Services' Technology Blog

A Mobile App Usability Tale…

2012-01-22T04:17:00.000-08:00

It’s often taken for granted that mobile apps are so simple that they don’t need online documentation or help. That may be true but it’s risky to assume that that’s always true. Here’s a case where it wasn’t.

There’s a game called Fruit Ninja (thanks, Sandra, I think…), also available on the iPhone. The object is to slice flying fruits in half with a sword, represented by your fingertip on the iPhone. The kicker is that the game periodically throws bombs at you. Slicing a bomb detonates it and ends the game.

I mentioned Fruit Ninja to a friend, who’ll remain nameless to spare him a lot of teasing (except from me, of course). I was on the phone with him last week and the subject turned to Fruit Ninja. He said it was fun but “what are you supposed to do with the damned bombs?”

It turned out that he had assumed that he was supposed to slice the bombs, like the fruit, but that there was a special way to do so to keep them from exploding. There isn’t. Hit them and they explode, period. I explained how to handle the bombs; he used several four-letter words, and said thanks…

I don’t want to read too much into this incident. This may be the only time it’s even happened. But this guy is a systems engineer for a large aerospace company, very bright, and he still misinterpreted the interface. My point is simply not to assume that everyone will understand how to use a mobile app.

Mobile eCommerce in Northern Vermont

2011-09-13T02:27:00.000-07:00

My wife and I were on vacation in northern Vermont last week and happened to stop at a farmer’s market in Morrisville. While I was wandering around, I stopped at a booth run by a woman selling meat and, after some discussion about the offerings, learned that she took credit cards by running the cards through a plug-in swipe unit from Square, at https://squareup.com/, that attached to her iPhone.

Two things struck me about this.

The fact that mobile ecommerce has penetrated a small town in Vermont with no high-tech tradition. In other words, mobile ecommerce is becoming ubiquitous.
The simplicity of the equipment and configuration. (See the Square site.) The woman said she wasn’t a techie, but found the equipment and the service a snap to use.

It's an increasingly mobile future...

Integrating Native Mobile Apps and “Help”

2011-08-18T14:01:00.000-07:00

We often view native mobile apps and online help/doc as distinct and separate types of online outputs. (And we can create online help/doc, which I’ll simply refer to as “help” from here on, in three “mobile” forms – mobile-optimized WebHelp, regular WebHelp viewed on a mobile device, and ebooks. So it’s crucial to define what we even mean when we talk about “mobile”.)

Can we connect these mobile types of “help” to native apps to add online help to the apps? That’s the subject of this paper – connecting native apps to “help” in the form of mobile-optimized WebHelp like Flare’s WebHelp Mobile.

But why bother? Native apps (Flixster, CamCard, etc.) are supposed to be so easy to use that they don’t need online help. But that’s not always true. Some apps have “hidden” interface features that must be documented. Others may require “domain” knowledge that has to be made available to users. We can provide some of this information within a native app, but native apps aren’t designed to handle large amounts of text. So how do we make help or domain knowledge available to mobile device users?

This paper answers this question by looking at three topics:

· Definitions – What’s a native app?

· Usage flow – How do native app users need to move between an app and its help? How can we make that happen?

· Design – What design criteria do we need to consider when interfacing native apps and help?

In this paper, I’ll show the specifics of interfacing native apps to “help” using two tools, an app creation tool called MobiFlex (http://mobiflex.me) and Flare (http://www.madcapsoftware.com) as the “help” creation tool, with a focus on the WebHelp Mobile output created in Flare 6 or 7. (If you don’t use Flare or MobiFlex, use the concepts as the basis for talks with your IT group.)

Definitions

Terminology misunderstandings often cause problems so, before proceeding, some definitions:

· App – Short for application but usually used in reference to mobile devices – e.g. “iPhone app”. Apps usually focus on one task, unlike feature-rich, often sprawling PC applications.

For this paper, I’ll define two types of apps:

· Native – Reside on the mobile device, are written in the device’s native language, and can use the device’s native resources – camera, accelerometer, GPS, etc. If the app collects or refers to data, that data can be on the device or on a server that the device accesses via the Internet.

· Web – Run in a browser on any device from a smartphone to a PC. WebHelp Mobile is basically a web app, which means that a native app should be able to link to it via a standard web link.

(A third type, hybrid, are native apps that run primarily in a browser but communicate with the device’s native resources (camera, etc.). I’m not covering these apps in this paper.)

With these definitions, let’s assume you created a native app for an iPhone or Android using MobiFlex and need to connect it to “help” created in Flare’s WebHelp Mobile format.

How To Connect a Native App to a Web App

For this paper, I’ll postulate two styles of help connection – “Help-menu” and “context-sensitive.”

Help Menu-Style

This style can simply be a link from the home page of an app to the home page of the WebHelp Mobile, similar to the Help > TOC option in a standard Windows application. For example, tapping the WebHelp Mobile button in the screen below:

…opens the WebHelp Mobile by launching a hyperlink to the URL of the WebHelp Mobile home page, shown below:

Once in the WebHelp Mobile, users can access the navigation featured defined in the WebHelp Mobile skin – Table of Contents, Index, etc. But how do users go from the WebHelp Mobile back to the app page where they launched the WebHelp Mobile? The solution is to add a “back” button, such as at the one at the upper left corner of the screen below.

This is easy. But what if you need more buttons? They’ll cover the WebHelp Mobile title bar. You could fix this by resizing and moving the window in which the WebHelp Mobile displays, as shown below.

This layout is similar to the previous one, except that I moved the WebHelp Mobile window down to add room for buttons without overwriting the WebHelp Mobile title bar. However, if all you need is a “Back” button, then this approach wastes a lot of already-limited screen space. It depends what you need to do. (You could also use a smaller button image for a better visual fit on the screen, as long as the button was still large enough to be easily tapped with a fingertip.)

Context Sensitive-Style

Context sensitive-style is similar to the Help menu-style above, with one big difference. The Help menu-style assumed you’d always go to the help from a specific app page and always return to that app page. This meant the “back” button could simply be a URL link to that app page.

Context sensitive-style still takes you from an app page to the help but the “back” button must now take you back to the app page where you launched the help, which may differ each time. This means that the “back” button can no longer be a URL link to one app page. Instead, it has to know your path through the material in order to provide a “back to previous” function. How you do this depends on the code you insert or the tool you use to create the app. (I’m assuming here that you created the help using Flare.) If you’re using MobiFlex’ visual authoring, here’s what the options look like:

This is the property sheet for an image button. The important part is the dropdown with “Go to previous page” selected. That’s all you need. It means that each page in an app can link to a page in the WebHelp Mobile. After users enter the WebHelp Mobile, move around it by using the WebHelp Mobile navigation features, and then decide to return to the app, tapping the “back” button takes them to the app page where they invoked the WebHelp Mobile in the first place. All controlled with one “back” button on the WebHelp Mobile page. The result is effectively context-sensitive help for the app pages.

Some Design Considerations

This process is mechanically straightforward, especially if using Flare and MobiFlex. But there are some design considerations to keep in mind. Here are three major ones:

· Should the app and the help look alike? It depend on your needs. You might say yes, to maintain visual consistency in the interface, or no, to visually distinguish the app from the help.

· If the app supports orientation shifting – e.g. shifting from portrait to landscape mode if the user moves the phone, should the help orientation shift too? If it doesn’t, might users get annoyed as they have to rotate the phone 90° each time they switch between the app and the help?

· Flare authors tend to think in landscape mode, but mobile devices may be portrait oriented. This means that Flare authors must create projects that can easily shift from the landscape mode of a PC screen to the portrait mode of a phone. That means using relative measures like % or em instead of points in the CSS.

You’ll probably find more specific issues of your own.

Summary

This simple visual approach (based on using tools like Flare and MobiFlex), breaks down walls between native apps and web apps like WebHelp Mobile. It lets technical communicators start creating online help for native apps, like we did for PC applications twenty years ago. It extends the capabilities of both tools. And technical communicators who become familiar with tools like MobiFlex can extend their skills into native mobile app development. The result is greater and more flexible development capability.

Note – If you’d like to see the app and WebHelp Mobile in action or see the underlying code, contact me at nperlin@nperlin.cnc.net and I can activate the app for you to try on an iPhone 4 or Android 2.2 phone or show the coding in MobiFlex.

Note - This post is also available on the MadCap Software site at http://www.madcapsoftware.com/company/industrybuzz.aspx

Answers to Last Questions From 8/10-11 Flare CSS Class

2011-08-12T12:07:00.000-07:00

Hi folks,

Here you go...

Re where else to find the description of the mc commands – download the Flare Styles Guide PDF (see the link in the footer in any Flare help topic). The commands were apparently added recently.

Re the topic popup style customization, covered on pg. 61 of the wokrbook, not working – the instructions in the workbook are correct. Tech support took a look, reapplied the popup style, and it worked. So either I misapplied the popup style to the link text or else I accidentally turned it off and didn’t notice that I’d done so. One of those forehead-slapping events that I mentioned.

Cheers,
Neil

Presenting Two Webinars On Mobile for MadCap Software

2011-06-17T03:00:00.000-07:00

Mobile has become a hot topic in the last few years, and you may be thinking about using it for your online help and documentation. But what benefits does it offer? For what kind of applications? What’s the difference between web apps, regular web sites, native apps, and ebooks, and how might those differences affect your mobile strategy?

You could buy and learn brand new types of software for creating mobile, with the effort and expense that entails. But if you have Flare 6 or 7, you’ve got an alternative – you can convert existing projects to mobile form with minimal expense and effort by simply using a few new Flare features and using some familiar Flare features in new ways.

This two-part webinar explores both issues – the general mobile “ecology” to provide a framework for your mobile strategy, and the specifics of creating mobile output using Flare.

Part 1 – “Native Apps?” “Web Apps?” What IS This Stuff? – An Overview of the Mobile Ecology

Part 1 looks at the general mobile ecology. We’ll review the rationales for and benefits of using mobile, some basic terms (feature phones vs. smartphones), delivery “mechanisms” (apps vs. sites vs. ebooks, etc.), major platforms (Android, Apple, etc.), the effect of device differences (such as how differences between smartphones and tablets may affect your choice of delivery mechanism), and suggestions on developing content strategy and standards, and market research to determine your direction.

Part 2 – “So How Do I Use Flare To Go Mobile?

Part 2 looks at the specifics of creating mobile output with Flare. We’ll review the overall process of converting a Flare project to the WebHelp Mobile output and look at typical results – what features convert well, poorly, or not at all, and the effect on workflows and project planning. Finally, we’ll do a live demo to see the process in action.

Part 1 - Jul 22, 10:00-11:00 am (Pacific Time)

Part 2 - Jul 27, 10:00-11:00 am (Pacific Time)

To sign up, go to http://www.madcapsoftware.com/demos/webinars.aspx

Responses to Questions From Last Week's STC Webinar on Content Strategy

2011-04-23T02:52:00.000-07:00

Kathryn S: On the "And Some Specific Ones..." slide, I just wanted to let you know you have a missing "s" on "ideas."
Neil – There’s always something... :-0 Thanks…

Tony C: Have you found any free offline validation tools? I like jigsaw too, but I work for companies that don't let me use externally hosted validators.
Neil – Good question. I Googled “w3c offline validator” and got a bunch of hits but I can’t speak about any of them. What I’d do is talk to your developers to see what offline validators, if any, they use, since they must have the same restrictions that you do. If that doesn’t help, ask the developers for recommendations for web developer forums, perhaps on LinkedIn and elsewhere, and post the question there.

Jody T: Do you think RoboHelp is becoming an obsolete tool? We have a very OLD version and we are working on moving documents to a SharePoint Content site(s)
Neil – Not at all. Any help authoring tool that survives in today’s competitive market is a solid tool. However, there are two additional considerations. First, RH is old (debuted in ’91, RH HTML in ‘98), so there’s a huge tail of legacy projects that Adobe has to support. Second, depending on how old your version is, you may be having problems because a) it IS an old version with bugs and peculiarities that may have been fixed in later releases but not in yours, and b) your authors may have done, and still be doing, things that go against today’s standards and best practices because those standards and practices didn’t exist when your company’s development practices evolved. There’s a lot more that can be said here but I don’t know how proprietary this issue is to you, so feel free to email me offline – nperlin@nperlin.cnc.net.

John L: How would you plan to include measurements and metrics that quantify a tech content creator's "productivity"?
Neil – You have to quantify productivity in two ways. One is obvious – metrics to see how efficiently you’re producing your doc. Those are essentially production metrics. Second, and more important, are strategic metrics, metrics that demonstrate how doc is helping the company with its larger strategic business mission. I’d have to know more about your company to get specific, but the obvious ones are things like reduced expenses (which is sort of like increased revenues) because of reduced tech support calls due to better doc, improved user retention due to better doc, an increase in the number of new customers because of the Captivate video of the product that you added to the company’s main web site, and so on.

Kathryn S: Can you give us a sample document or template that we can base our strategies on?
Neil – Companies are so different that it’s hard to say, beyond what I noted in the webinar, without much more specific detail. However, I’d mentioned what I consider to be a useful thought-provoker and promised to list it – it’s a book called “Maximizing Project Value”, Jeff Berman, AMA Books, www.amacombooks.com. It is something of a marketing blurb for a project metric methodology, but he does add what I consider to be a lot of thought-provokers. I’ll add (sales pitch warning) that I do this on a consulting basis and would be happy to talk to you offline if you’re interested. You’ll also find a number of presentations on the subject at the Summit if you happen to be going.

David C: Looking for starter info for application of content strategy in a research org like a GOV agency where the primary web content is information and publications
Neil – Without a lot more detail, I’d tell you to see my previous response to Kathryn S. We can also talk at the Summit.

Hope this helps.

Regards and thanks for attending,
Neil

“Mark of the…” What?

2011-03-24T04:17:00.000-07:00

If you use MadCap Flare, Adobe RoboHelp, and probably any other HAT (help authoring tool), you may have noticed the intriguingly-named Mark of the Web option in the output settings. Mark of the Beast jokes aside, what is this?

If you use IE 7 or 8 (and some earlier service packs), you know that after you generate a browser-based output like WebHelp and then try to view it, the output doesn’t display. Instead, the browser opens with a yellow bar that reads “To help protect your security…” just above the display area. To view the output, you must click on the blocked content bar, click the Allow Blocked Content… option, and finally click Yes to the security warning message. Only then does the output display.

The blocked content… feature has nothing to do with help authoring per se. It’s a security feature in IE that has the side effect of blocking the display of HTML and XHTML files, which the help topics are, when you run them from your local PC. Where help authoring is concerned, it’s harmless but mildly irritating. Selecting the Mark of the Web feature, often referred to as MOTW, lets you deal with that irritation by turning off the blocked content bar and displaying your output immediately.

According to MSDN…

“The Mark of the Web (MOTW) is a feature of Windows Internet Explorer that enhances security by enabling Internet Explorer to force webpages to run in the security zone of the location the page was saved from—as long as that security zone is more restrictive than the Local Machine zone—instead of the Local Machine zone. When you are developing webpages, the MOTW enables you to test your HTML documents in the security zone where you intend the pages to run. Adding the MOTW to your webpages also enables you to fully test their compatibility with users' security settings.” (http://msdn.microsoft.com/en-us/library/ms537628(v=vs.85).aspx)

So why not turn on MOTW all the time? The blocked content bar only appears when you view your output or HTML/XHTML files on your local PC. It does not appear when you view your output or HTML/XHTML files on a network drive or server. So if users will view your output on a network drive or server, there’s no reason to use MOTW. If users will view your output locally, on the C drive, for example, you might use MOTW. But be aware that MOTW also causes two odd problems in help authoring:

• If you created links in your topics and turn MOTW on, those links don’t work when you preview topics in your HAT. Confusingly, however, they do work in the output. So there’s the risk of wasting time trying to figure out why the links don’t work except when they do.

• If you created links in your topics to external files like PDFs and turn MOTW on, the external links don’t work in the preview or output. They look fine… they just don’t work. So, again, there’s the risk of wasting time trying to figure out why regular links do work but external links don’t. It’s a problem whose solution – turn off MOTW – is simple but totally unintuitive.

The upshot… You might want to turn MOTW on during development to avoid having to click through the blocked content bar each time you review the interim output. Just be aware of the authoring problems and be sure to turn MOTW off when you generate your final output.

Thanks to Jerry in San Jose and the crew is Brisbane for motivating me to finally write this. :-)

What’s New in Flare 7 – QR Codes

2011-03-12T02:44:00.000-08:00

Continuing my posts about features in version 7 of MadCap Flare… Here, I’ll look at one of the more unusual features – QR Codes.

QR codes are one of those features that’s so unusual that the first reaction is “um, yes…” followed by “Whoa!” (Another such feature is the toggler link.) If you’ve recently seen something that looks like this, you saw a QR code.

Think of QR codes as an expanded form of the familiar bar code. QR (Quick Response) codes were created, according to Wikipedia (http://en.wikipedia.org/wiki/QR_Code) by Toyota subsidiary Denso-Wave in 1994 for parts tracking during manufacturing and are read by dedicated readers for manufacturing. But what makes them interesting for tech comm is the spread of smartphones equipped with readers. Scanning the code above on my smartphone registers a link to my web site at www.hyperword.com. Clicking that link then jumps to the site, without having to physically type a URL.

What can you do with QR codes? Here are some examples, starting with three from the “About QR Code” topic in the Flare online help:

• You want to give users the ability to jump to your company web site from a PDF or print manual. You could list the URL for users to type, but instead you insert a QR code containing the URL. Users can simply point their smartphones at the code to read the URL, then launch it.

• You’re creating a quick reference guide. Like all such guides, it sharply limits the amount of information you can include, so you give users access to further details by inserting QR codes in the quick reference that link to the full documentation in the form of a WebHelp-based help system on a server. Or the codes might jump to web pages running videos or SWF movies showing how to perform a related task mentioned in the quick reference.

• You could use the codes as a sales tool. For example, you put a QR code on the cover of a sales brochure. When readers scan that code, it takes them to a web page where they can order your product.

And from my own experiments, experience, and research, use it:

• As a brand differentiator – like a sales tool but one that says to certain audiences that you’re cooler than your competitors.

• As a sales tool in situations where prospective customers can’t write down your information because they’re driving or hanging onto a strap on a subway. (I recently saw a two foot high QR code painted on the back of a delivery service truck. If I was interested in the service and had my smartphone at hand, I could have simply scanned the code and gotten the URL for the company.)

• For marketing with response tracking. There are a number of useful threads about this on the Mobile Content group under LinkedIn.

• For any other case where it’s just inconvenient to type a URL. (I have large hands and find it very difficult to type on a smartphone keyboard, virtual or real. I’d find a QR code a helpful substitute.)

How to read QR codes on your smartphone? Easy – get a reader app from your vendor’s app store/market. I have two, ConnectMe QR for my iPhone 4 and Google Goggles for my Android phone, a Samsung Captivate. Both worked like a charm, and are free. Start the app, point the camera at the QR code, and wait a few seconds. Each app read the QR code and popped up the information on the screen. For example, the QR code I showed above is for my web site at http://www.hyperword.com/. Here’s how the ConnectMe QR app read it off my laptop screen in about a second:

So how do you create these codes using Flare? It’s almost the same as inserting a graphic, the difference being that you can actually see Flare’s QR code generator create the code as you specify the code’s content. To do this:

Click in a topic where you want to add the code and select Insert > QR Code. In the Insert QR Code dialog box, select the content type – Text, URL, Email…, Contact Information, or SMS. The dialog box settings change accordingly. For example, if you select Text, Flare simply waits for you to start typing. However, if you select Contact Information, fields appear for Name, Company, and so on. Fill them out and you’ll see the code taking shape in the Preview pane.

You can also control the size of the code, which may be handy if you create one with lots of information that may be read in shaky or blurry environments. For example, I found that when I entered some marketing text (see the next paragraph) and used the default code size, both my readers took longer to interpret the code than they did when I enlarged the code. I’m not sure if that was the reason why but the difference was noticeable. Finally, you can attach a style class and a screen tip to the code and set display elements like position, borders, margins, and a background.

Is there a limit as to how much you can put into a QR code? Yes, depending on the nature of the content - 4296 alphabetic characters or 7089 numeric characters, with some variations - according to an article at http://qrbcn.com/imatgesbloc/Three_QR_Code.pdf. It should be enough for many uses. Here, for example, is a marketing piece about an upcoming mobile app authoring class that I’m teaching – “Mobile app authoring without coding – ½ day remote class on 3/21/11 – contact nperlin@nperlin.cnc.net for information”

Here’s what the code looks like:

And here’s the perfect result:

I’m not sure yet of everything for which I might use QR codes, but I can see a lot of possibilities.

More to come…

What's New In Flare 7

2011-03-07T12:24:00.000-08:00

This is the first of several posts on the newly-released version 7 of MadCap Flare. Flare 7 adds many new features, including more powerful SharePoint support, native Subversion support, support for vector graphic formats like EPS and SVG (Scalable Vector Graphics), linking to external files to use in multiple projects, a revised editor for adding and maintaining context-sensitivity codes, the ability to preview topics in any target you defined, the ability to view generated output in any browser on your PC, QR (Quick Response) codes, an equation editor that uses MathML (Mathematics Markup Language), numerous enhancements to table support, and more. In this post, I’ll look at the support for tables, a seemingly mundane feature that’s actually anything but.

Tables can be troublesome, especially those in topics created by imported Word or Frame files. Flare has had some powerful table features since v. 1, but v. 7 adds some significant extensions. Here’s a quick look at some of what I consider to be the most significant.

Revised Table Style Editor

The TableStyle editor hasn’t changed for a while, but has been reorganized in v. 7. Here’s the TableStyle editor in v. 6 for reference:

And here it is in v. 7:

Note several changes…

• The generic term “patterns”, referring to groupings of row/column/etc. properties, is now more element-specific – “row styles”, “column styles”, etc.

• It’s easier to change the sequence in which particular row or column styles should apply in a table. For example, if you created row style 1 with a green background and row style 2 with a red background and then decide to reverse their sequence, you can simply click on either of the styles, then click the up or down arrow to the right of the style.

• Features are now functionally grouped – “Column Properties” and “Background” – rather than appearing somewhat scattered around the editor screen. I believe this improves the overall usability of the editor.

The TableStyle editor’s title bar also adds two features – Medium and Apply Style….

• Medium adds the power of mediums in the regular Stylesheet editor to tables. If you’re new to mediums…

Mediums are alternate groups of properties for alternate outputs in one table style sheet. Let’s say you output to WebHelp and PDF and want to use navy for header rows in WebHelp but black in PDF, and keep all the other table styles the same. You might create one table style sheet with separate mediums for WebHelp and PDF, assign different values to the header for each medium, then tell Flare which medium, and thus header values, to use for which output. For example, you might select your PDF medium to set all header rows to black for a PDF target, and the Default medium to set all header rows to navy for WebHelp – all from one table style sheet.

This can reduce your table style maintenance work since there’s only one table style sheet to maintain and just a few settings to actually define for each medium. Mediums can be confusing if you’re not careful, but the reduction in maintenance work makes them very useful for single sourcing to different formats and output devices.

• Apply Style… lets you select multiple topics, or folders-full of topics, to which to apply a table style sheet. You can also overwrite existing table styles and remove local formatting in the tables. The former is useful; the latter may be enormously useful if you import legacy Word files containing tables.

There’s another feature on the editor that’s easy to miss because of an interface change in Flare 7. In 6, there was only one vertical scroll bar for the TableStyle editor, as shown in the image below.

In 7, below, there are two vertical scroll bars, one for the upper (settings) portion of the editor and one for the lower (preview) portion. Why does this matter?

• One is convenience. In 6, if you wanted to see the options in the lower part of the settings section, you might have to shrink the preview section. In v. 7, you can just scroll down the settings section without changing the size of the preview section.

• There’s also a new feature. Scroll down the settings portion of the editor in 7 and you’ll see an Advanced button at the bottom of the …Properties section. Clicking it displays a Breaks control dialog box that lets you further format the table.

Two more features that many people, including me, have wanted have now been added – the ability to convert tables to text and vice versa. You could convert text to a table by inserting a new table and dragging the text into the cells, but that’s slow. Better to be able to select text and convert it to a table in one step. The feature isn’t immediately obvious; you’ll look on the Table menu for a Convert Text to Table feature and not find it. It’s actually on the Insert Table dialog box in the Text to Table section, shown below, with options for splitting the text on paragraphs, commas, or other markers.

How well it works in practice depends on the cleanliness of the text. Ignoring that issue, this should be a very good productivity improvement feature.

Some other useful new features include merging adjacent tables, not just adjacent cells, and pasting cells from one table into another. You can also merge, split, and clear cells, apply and change cell content styles and cell classes, resize tables, all features that date to v. 6 or earlier and have been retained in v. 7.

The table features also offer two tricks that can fix some annoying problems you may run into. These tricks aren’t new but you may not know about them if you haven’t taken one of the training classes, talked to a consultant, or just experimented a lot.

Trick 1 – Local Formatting In Tables Breaks Table Style Sheets

Ever apply a table style sheet to a table and find that some settings don’t work for some reason? Often, the problem is that the table contains local formatting. This can happen in tables in topics created from imported Word documents, or tables created in Flare and hand-formatted to get a particular look. Local formatting overrides styles in table (or any) style sheets. You can try to fix the problem by playing with the styles, but you may find yourself flailing. Or you can go into code to find and delete the local formatting code, but this can be difficult. (The first figure below shows a little table, the second shows the underlying code. It’s not easy to find the bad code in this.)

There’s a simpler way. Click in the table in the XML editor and select Table > Reset Local Cell Formatting. This automatically finds and deletes the offending code and the table style works instantly. This feature can fail on very problematic tables, but I find that it generally does work and, when it does, it’s sort of like magic.

Trick 2 – Header Row Settings in My Table Style Sheet Don’t Work

The TableStyle editor lets you define a header row as a separate item with its own distinct styles within a table. However, you may find that your header row styles don’t work on some tables. Often, you’ll find that these tables came in from Word files. In Word, if you’re like me, you count the number of rows needed for a table, then add one more to act as a header row. But Flare sees this as an ordinary row that’s acting as a header, not a programmatically defined header row, so the header styles don’t work. How to add a header row to these tables to get your header styles to work? It’s surprisingly easy.

Step 1 is to add the “Flare-compliant” header row. Click in the table, select Table > Table Properties, make sure you’re on the General tab, and change the Number of Header Rows field from 0 to 1. You’ve just added the programmatic header row. Step 2 is to move the column heads from their current row to the “real” header row. When you do, they take on the styles you defined for the header row in the TableStyle editor. You can then delete the original and now empty header row. That’s it.

Overall, a well laid out set of table manipulation features with some very useful additions.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 12

2010-12-21T05:41:00.000-08:00

Four separate but closely related recommendations regarding any text entry…

5. [URIs] – Keep the URIs of site entry points short.

54. [MINIMIZE KEYSTROKES] – Keep the number of keystrokes to a minimum.

55. [AVOID FREE TEXT] – Avoid free text entry where possible.

56. [PROVIDE DETAULTS] – Provide pre-selected default values where possible.

The gist of these points is that it’s hard to type on a mobile device keyboard, whether real or virtual. Mobile device users text like mad so it’s certainly possible, but if you have big hands or are in unstable environments, you’re likely to have problems typing. This is true especially where accuracy is important, such as typing URLs as opposed to text. (Speaking from experience with my latest smartphone, a Samsung Captivate with a large virtual keyboard, I still have to tap the keys with a fingernail and watch what I type very carefully.)

What this suggests is eliminating any free text entry if possible, and minimizing the rest. More specifically, with regard to the four points above…

Minimize the length of any URI that viewers have to type. The W3C recommends setting up any target web sites so that viewers can access them without having to type a sub-domain as part of the URI. For example, rather than requiring users to type this:

http://www.example.org/index.html

Let them type:

http://example.org

The “www.’ portion isn’t hard, and many mobile device keyboards have pre-set “www.” keys anyway. It’s more the length of what follows the www, such as:

http://www.economist.com/node/17722664?story_id=17722664

One easy, albeit tedious step, is to run URLs through a URL compressor like TinyURL, www.tinyurl.com. For example, it compressed the long and hard-to-type URL above from 56 characters to 26, as shown below:

http://tinyurl.com/28hzyj6

It’s still no treat to type, but there less of it. And if you can replace the typing of URIs with pre-defined links, so much the better.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 11

2010-12-07T04:25:00.000-08:00

A recommendation regarding graphics…

25. [LARGE GRAPHICS] – Do not use images that cannot be rendered by the device. Avoid large or high resolution images except where critical information would otherwise be lost.

Whether to show graphics has always been a design issue in online help/doc, but one graphics issue that hasn’t been a problem until now is size. Desktop and laptop displays are large enough to show all but the largest graphics; the few that were too large usually needed just minimal scrolling. This ease of use often leads authors to add graphics with abandon. However…

Mobile device screens, except perhaps those on iPads, are so tiny that all but the smallest graphics require scrolling. And there doesn’t seem to be any good technical solution; the solution is information management – re-examine our projects to see if the graphics are really necessary and:

• If a graphic is not necessary, delete it.

• If a graphic is necessary, try to crop it to eliminate extraneous information and focus on just the salient portion.

• If the entire graphic is necessary, see if it can be scaled down.

• If scaling fails because the result is too small to read, accept the idea that some content just may not fit your design but still has to be included because the content is more important than the design.

• If a graphic works on large-screen devices and is nice to have, but causes design and usability problems on mobile devices, you can use conditionality to flag and exclude that graphic from mobile outputs. This is just one more way to use the conditionality feature in our help authoring tools.

MadCap Flare does offer one partial technical solution – the thumbnail attribute for the img tag. This feature lets authors display a graphic as a thumbnail until viewers click on or hover over the image, at which point it expands to a pre-defined size. It’s a nice way to insert graphics in topics but minimize their space requirements until viewers want to see them. However, the hover or popup display effect converts to a jump link in Flare’s mobile output, presumably because MadCap could not be sure if a particular mobile device supported hover or popup – presumably none did at the time – and so converted the thumbnail display effect to a safe, regular jump link.

• If you must include an entire, large graphic, you might use image maps to link areas of the graphic to other pages that offer more detail. But many mobile devices don’t support image maps. Those that do may not offer any way to reach a hotspot except by using the up, down, left, or right movement function. This type of movement works but is tedious if you need to reach a hotspot far down on a hotspot-rich image map.

• It is also possible to eliminate the whole too-large-graphic issue by simply including the graphic at whatever size is necessary and zooming the display. The problem with this approach, however, is that it re-introduces horizontal and vertical scrolling.

(I’ve often wondered why virtual reality glasses never took off since they solve the whole problem of limited screen size. But they haven’t.)

So the best way to deal with large graphics on mobile devices is to re-evaluate the content to see if those graphics, or any graphics, are really needed, get rid of those that aren’t, modify those that are, and accept the result. This may take a lot of work in large projects. But bear in mind that if you’re going to output your online help/doc to mobile, you may be doing so many other “clean-up” steps, such as eliminating hard returns between paragraphs or changing CSS size settings to relative units, that re-evaluating graphics may be just one more task in the shift to mobile.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 10

2010-11-24T04:17:00.000-08:00

A recommendation regarding terse markup…

45. [MINIMIZE] – Use terse, efficient markup.

I noted in part 9 that the desktops and laptops for which we create online content have so much power that we often code verbosely and inefficiently because we can. And it’s less work. I was referring to style sheets there, but the same point is true for markup in topics.

The issue of terse, efficient markup falls into several areas. In each case, we have to ask whether the benefit is worth the effort.

Redundant White Space

One area, according to the W3C, is that “content …marked up in… XML can… be made smaller while preserving… semantics by removal of redundant white space (i.e. spaces and new lines).” It isn’t clear, but I think what the W3C is referring to is white space and new lines in code view, not WYSIWYG, but there is an efficiency issue in WYSIWYG too so I’ll look at that as well.

Code View – “Pretty Printing”

The W3C suggests avoiding “pretty printing,” the formatting of markup with indentation, because it “can generate large amounts of white space and… add to page weight.” But it also notes that “pretty printing” may be an important part of the authoring, in which case “try to arrange that redundant white space is stripped when serving a page.” It further notes that “…some network proxies strip white space that they think is redundant, [but] not all do so, so… not… to rely upon this behavior.” What is this about?

Look at a topic in code view in your authoring tool. You’ll see something like this:

Note the indentation and new lines, all of which add space. For example, the code above uses 194 bytes. Collapsing the indents to look like this:

reduces the size to 184 bytes, a 5.1% drop. And this:

reduces it to 172 bytes. So eliminating the indentation and white space reduces the size of the file from 194 bytes, or 11.3%. (Your numbers will differ.) This may seem trivial, but smaller files reduce network traffic load. However, the increased terseness and efficiency of the markup also makes the code less readable. The first example is easier to read than the second and certainly the third.

This may force you to weigh the need to work at the code level versus code efficiency. If code efficiency is most important, you’d buy the most efficient authoring tool you can and make it a policy not to work in code except in unusual cases. Conversely, if you want to be able to work in code, you may go with a tool that creates less efficient markup. Talk to Engineering or IT about this.

WYSIWYG View

HTML and XHTML collapse multiple character spaces, so we can’t use multiple spaces to indent text. However, one thing we often do is add a line space between paragraphs, a bad habit left over from our word-processing days, rather than adding a “space after” or bottom-margin property to Normal and other body-content related styles. Does doing so reduce file size? Based on a rough test, yes.

I created a topic with five lines of text, effectively paragraphs, in Normal style, with one line space after each paragraph and a bottom margin of 0 in Normal style. The file size was 630 bytes. When I set the bottom margin to 1.12 em in Normal style and deleted the line spaces, the file size dropped to 538 bytes, a 14.6% drop. (Again, your numbers will differ.)

I always suggest that clients and attendees in training classes set paragraph spacing using a top and bottom margin setting for the Normal style in the CSS simply because the more we control through the CSS rather than by local formatting, the more future-proofed our content is. A file size reduction of this magnitude is just one more reason to get rid of hard line spaces between paragraphs.

Excess Code

We may also find that our topics contain additional, proprietary codes. Some are inserted by our help authoring tool to add custom features. Others may appear in topics created by importing Word files into the help authoring tool. These extra codes increase the file size. It is worth trying to get rid of them?

If we plan to keep our current authoring tool, then any proprietary code can probably stay in the file, even if the code is inelegant. However, this can be risky if we’ve been using a particular tool for years and take the proprietary codes for granted, only to learn that they don’t convert well when we change tools or formats and must be fixed by hand. Because of that, it’s a good idea to periodically review a sample of topic files created by our tools and check the codes to see what’s standard and non-standard.

A similar problem occurs in topics created by importing Word files. The files often have Word-specific code that may not harm the topics but do increase their file sizes. And it is possible that those Word-specific codes might cause trouble during some conversion in the future. So, again, it’s a good idea to periodically review a sample of topics created from Word files and check the codes to see what’s standard and non-standard. I don’t know of any specific references for this, but I recently read a book called ePub Straight to the Point by Elizabeth Castro, published by Peachpit Press in 2011, that discusses how to convert Word files to ePub format. In the discussion, Castro explains what many of the Word codes are and how to delete them. I don’t think it’s the complete answer but it is worth a look.

The big problem in deleting excess, proprietary code added by an authoring tool or Word is simply the greater knowledge required to do so and the risk of breaking something. So while eliminating these codes may increase terseness and efficiency and reduce file size, it seems like the most difficult part of the job and one to be approached very carefully and after some experimentation.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 9

2010-11-22T09:42:00.000-08:00

A recommendation regarding style sheet efficiency…

44. [STYLE SHEETS SIZE] – Keep style sheets small.

The desktops and laptops for which we create online content have so much power that we often code inefficiently because we can get away with it, and it’s less work than coding efficiently. But mobile devices lack the power and resources of desktops and laptops, so they force us toward more optimized control files.

One of the most important of those files is the CSS, and one issue is whether our target mobile devices support CSS caching… After a device has retrieved the CSS for a topic, will it store that CSS to use for the next topic or does it have to retrieve the CSS again for the next topic? If so, we want to keep the CSS small to use minimal device resources. If the device does not support caching, it may have to retrieve the CSS for each topic. If so, we still want the CSS small to reduce network traffic for the repeated downloads of the CSS for each topic.

The W3C notes several ways to keep CSSs small but the simplest is to “…optimize style information so that only styles that are used are included.” How does this apply to help?

When our help authoring tools create style sheets, they include a default set of styles, like heads 1 - 6. The problem is that we often accept that set of default styles, even though we never use some of them in our topics. Those unused styles simply make our CSSs larger to no purpose. The solution is to remove the unused styles from the CSS. How?

We can easily remove unused styles through the authoring tool interface. But how do we know if those styles are really unused? Even if we keep careful records of style usage, it’s difficult to be sure - especially when dealing with legacy projects or large projects that we’re not totally familiar with.

A better idea is to search for the style codes in the topic code. Use the authoring tool’s multi-file search feature to look for the questionable codes within all the topics in the project. If the search doesn’t find any hits, then delete the style code from the CSS. This is a sure-fire approach technically, but it can be slow and tedious to work your way through a large and complex CSS or one that you have not checked for a while.

So the best solution here isn’t technical but managerial. Create a standard CSS for all authors to use, do one search pass through your legacy topics to clean up the style codes they contain, and prohibit ad hoc modification of the CSS after that. It’s one more argument in favor of standards.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 8

2010-11-11T06:02:00.000-08:00

Another recommendation regarding formatting.

41. [MEASURES] – Do not use pixel measures and do not use absolute units in markup language attribute values and style sheet property values.

I discussed absolute vs. relative units in part 2 in relation to scrolling, but I’ll define this issue again here and expand on it.

From my consulting and training experience, I find that authors usually define the size of fonts and spacing in points, such as 10pt for Normal text. Two reasons for this:

• Many help authoring tools, like RoboHelp, use points as the default so we’ve just gotten used to it.

• For authors who come from hard-copy, especially Word, points is the default and an easily visualized unit – 1 point = 1/72”, so 12 points = 1/6”…, for example

But when we put content online, absolute units like points cause trouble for two reasons.

• Different display technologies may render points differently. For example, 10 pt is standard for Normal text on PC displays but too small on Macs because of the different technologies. So if you’re creating online material that might be read on PCs and Macs, you’d need two CSSs, one for each, with two different sizes for Normal text.

This isn’t a problem if you create online content for local use on one platform, such as HTML Help on PCs. But if you have to convert that content to a format like WebHelp that might sit on a server and be accessed by users with different platforms, like PCs and Macs, this does become a problem.

• Browsers can’t resize point-based text.

Going relative fixes these problems easily, once you get used to thinking in this new way. Relative units replace points, pixels, inches, etc., with units like % or ems. The benefit of relative units is that they automatically adapt, under the browser’s control, to the space on a given display.

For example, a graphic that’s 180 pixels wide might be fine on a standard display but too wide for a mobile device, so the device adds a horizontal scroll bar. Horizontal scrolling isn’t evil, but it does reduce usability, especially if you have to scroll vertically and horizontally, so you want to avoid it where possible.

Setting the width to 100% fixes the problem. This says that the graphic should display at 100% of the available space and leaves it up to the browser to figure out what that is.

This approach isn’t perfect. It’s possible to apply relative size to a graphic which displays it correctly but makes it too small to read. Or it may not display correctly in certain cases, such as within table cells in ePub format running in the Adobe Digital Editions (ADE) viewer. Still trying to track this one down…

What relative units can you use? There are several, including %, ems, and exes. The % is relative to the size of Normal style at 100% on any browser. So, for example, setting h1 style to 150% says that all heading 1 text should be half again as large as Normal text on each browser. (This isn’t exactly the case, but it’s close enough to get a mental picture.) The em is based on the baseline height of the m on the browser. The ex is similar to the em but based on the x.

Of these three, the most widely supported (a totally unscientific statement based solely on experience) are % and em. Some people prefer the em. Others, myself included, prefer the % because it’s easier to picture mentally. Pick the one that makes the most sense for you and is easiest to use.

Next, keeping style sheets small and using terse, efficient markup…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 7

2010-11-03T01:48:00.000-07:00

Several inter-related recommendations regarding content formatting.

53. [FONTS] – Do not rely on support of font related styling.

Per the W3C – “Mobile devices often have few fonts and limited support for font sizes and effects (bold, italic, etc). …use of font size, face, or effect, for example to highlight an answer or a stressed word may not achieve the desired result.”

This seems obvious. So how does it affect tech comm?

If you’re creating “true” mobile apps, they may have little or no font related styling since you’ll be creating the apps from scratch and thus, hopefully, following best practices. But if you’re mobilizing an existing online doc or help project, it may have lots of font related styling, bold or italics, because it was created at a time when styles and style sheets didn’t have the importance they do now. Those font related styles in your material can affect your project planning, development style, and development process.

1. You have to find out if the devices you’re publishing to can support font related styling. If so, the styling becomes a best practices issue instead of an immediate programming crisis. But even if it’s not a crisis, font related styling, essentially local formatting, is still bad practice in an increasingly single sourced world and will affect your projects eventually. And if any of your target devices don’t support font related styling, you’ll have to deal with it now. To do so…

2. You have to get rid of it. This isn’t difficult but it is tedious, especially if there’s a lot to get rid of. You may have to do large-scale search and replaces in the code to replace local formatting with character styles. This works but it’s scary, even if you’ve backed up the project. More difficult still…

3. You have to stop using font related styling, possibly a major change in how you work. It’s simple mechanically – add bold and italic character styles to the project CSS. What’s hard is breaking old work habits, no longer using the text formatting toolbar in Flare or RoboHelp, for example. This can be surprisingly difficult.

So if font related styling is now off the table, how do we format text?

42. [STYLE SHEETS USE] – Use style sheets to control layout and presentation, unless the device is known not to support them.

Style sheet, or CSS, use has been growing in tech comm for years but still isn’t as widely or consistently used as it should be. CSS styles are used on heads and body content in online help and doc, but less often for things like bulleted or numbered lists, tables, notes, cautions, etc. More rarely still are CSS styles used for text enhancement, again because the text formatting toolbar is so convenient. Some authors are also deterred by the need to create a separate CSS for each target mobile device. (This isn’t necessary – instead, the solution is the media types feature in the W3C’s CSS spec, MadCap Flare’s “mediums”, but this feature is still not that widely known.) There’s also uncertainty in some Word shops about the distinction between how styles work in Word vs. in HTML/XHTML.

The upshot? Any doc group that sees single sourcing to mobile in its future should plan to train all authors on the concepts and use of style sheets and new development processes so as to reduce or even eliminate local formatting.

There’s more to this issue as well, including:

• The need to organize documents so that they can be read without style sheets if a particular mobile device doesn’t support them.

• Editing style sheets to minimize their file size.

• Using relative measures in place of absolute measures like pixels and points.

To be covered in the next installment…

A Few More Questions From Last Week's CSS Class...

2010-10-26T05:12:00.000-07:00

Overlooked a few...

Q. If you create a custom style, like Note in the exercise, and set a background color for it, how do you narrow the style so that it does not run from the left border to the right border but instead looks more like a colored box?

A. Select the style in the Stylesheet Editor, open the Box properties group, and set the margins using the Margin-right and Margin-left properties.

Q. If you've applied a character format from the style sheet, such as applying the bold style from the Styles pane, how do you turn off that formatting and go back to plain text?

A. This changed a bit in Flare 6 from earlier versions, so you can't right-click on the formatted text and select Unbind on the popup menu. Instead, double-click on the formatted text to highlight it, then click on the formatted text once more, then right-click on it and select Unbind on the popup menu.

Q. How to control the alignment of hanging indents like bulleted or numbered lists?

A. Use the Margin-left property in the Box properties group on the Stylesheet Editor.

This time, I really think that's it...

Responses to Questions From Last Week's Remote Flare CSS Class

2010-10-25T10:50:00.000-07:00

Hello,

I think this should take care of the remaining questions from last week's CSS class. If it does not, please email me directly:

From AS:

1. Is there a feature in table styles or style sheets that could be set so table rows NEVER break across a page? (In Author-It we currently select all our table rows in a table, and simply click an icon that applies this option.)

Try this - in the Stylesheet editor, select the TD style, open the PrintSupport property group, open the Page-Break-Inside property, and select Avoid.

2. Is there a way to control orphans or widows other than by "lines"? Currently we are monitoring these in print very manually because we want to keep entire paragraphs and/or list items together. So when we output to print (Word) we go through the entire document, and for any such situations we have to select the text, choose Paragraph Properties > Keep with Next.

No. This is apparently limited to "lines" as units, per the CSS spec according to tech support.

From JK:

Sometimes when I am working on a topic page I will get these blank open spaces between my heading and paragraph blocks. Do you know what causes the blank open spaces and how to remove them?

Check the margin settings on the offending style, the h6 in your example. If that's not the problem, look for another head style above or below the offending style, as in the h1 above the h6 in your example, and check ITS margins.

Two of you had very specific questions that I'll address individually. Aside from those, I think this is it. Nice working with you all.

Regards,
Neil

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 6

2010-10-25T02:59:00.000-07:00

Two recommendations related to the “size” of a “page”, or topic.

20. [PAGE SIZE USABLE] – Divide pages into usable but limited size portions.

21. [PAGE SIZE LIMIT] – Ensure that the overall size of [the] page is appropriate to the memory limitations of the device.

These recommendations relate to the issues of content quantity and file size.

For content quantity, the issue is how much content to put in one topic versus breaking that content into several smaller topics. This is partly related to topic-based authoring and partly just an arbitrary issue of file size.

“Topic-based authoring” says we create content in small, fairly self-contained units – topics. “Fairly self-contained” means that each topic tries to answer one question – “what is”, “how do I”, etc – with related but separate information in separate but linked topics. For example, consider changing a tire on a car.

One topic might cover the steps for changing the tire, and link to another topic that covers safe jacking practices, another that explains where to find the jack and lug wrench, etc. This structure, plus tight writing in general, keeps each topic as small as possible. But is isn’t perfect; different topics may follow the same “one-question” model but still have very different lengths. For example, a command reference section in a programming manual might cover command A in a quarter of a page but need three pages to cover command B.

On large-screen devices, this may be a design problem but isn’t a technical problem. The browser or help engine will display topics that are as long as you need, even if you don’t like the excessive scrolling. If the scrolling is too bad, you can add an “in-topic” links list at the top of the topic to let users jump directly to a desired section in the topic.

In mobile, however, length raises many problems. Reading scrolling material is hard on large screens but worse on small ones because you see less material per screen. Zoom the mobile screen to make the text legible and you’ll see still less plus add horizontal scrolling to the vertical scrolling. The “in-topic” link list idea just takes up valuable screen space. And, a long topic that works on a large-screen device may exceed a mobile device’s file size limits and get truncated on the display.

What to do about these problems?

• If you create content now for large-screen devices but see mobile being added to the mix, you first need to know the file size limits of the mobile devices you’ll be supporting.

• Based on those limits, you need to review your topic lengths to see if any are too long and, if they are, break them into separate smaller topics and/or edit them.

• Also, if you don’t use any particular methodology for writing content now, or if you’re coming to mobile from a hard-copy output environment, look at topic-based and structured authoring to see whether they’ll help you a) define consistent information types, b) create topic templates that you can use to apply a consistent structure to the material, and c) break the material into smaller topics based on the information type analysis. (There’s a degree of self-interest in this paragraph since I teach topic-based and structured authoring, but that doesn’t reduce its utility.)

• Finally, if you haven’t reviewed your content for a while, this is the time to see if your editorial standards have slipped a bit and let fat creep into the writing.

In summary, topic length issues depend on two things, much as in the previous post:

• Knowledge of technical issues – what devices, microbrowsers, standards, etc. will you use and what file size/topic length limits they impose?

• Knowledge of strategic content issues – what outputs do you need, what content applies to those outputs, and how to define and control that content?

Again, needs assessment and configuration analysis before moving to mobile – the same things we’ve always had to do but taken in some new and sometimes extreme directions.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 5

2010-10-21T04:21:00.000-07:00

Next, a recommendation that applies to a common feature in online help and doc, popups.

13. [POP UPS] – Do not cause pop-ups or other windows to appear and do not change the current window without informing the user.

The first part, about pop-ups or other windows, is what most applies to tech comm. The W3C states “Many mobile devices cannot support more than one window… attempting to open one will have unpredictable results.”

It’s safe to assume that, for now, the mobile devices we use can’t show popups. Trying to open a popup may produce an error message, as in RoboHelp’s ePub, get converted to a jump link, as in Flare’s WebHelp Mobile, or do something else unpredictable. But popups are common in online documents and online help. What do we do?

The answer is to back up to the top level of abstraction and define two things, our project's outputs and their priority. We’ll then define a feature set based on the priorities. For example, do we want online help and hard-copy, with online having top priority? If so, we’ll define a feature set that’s best for online but may not convert to and work as well in hard-copy. If our priorities change, the feature set may have to change to match. (The authoring tool may even have to change.) The crucial thing is to consider how the feature set will work across all the desired outputs, not just focus on the top priority output.

Consider this approach in regard to popups …

• If our outputs are online and mobile and online has top priority, we pick features that are most effective for online and conditionalize them out for mobile. For example, we create popups and use them in the online output but conditionalize them out for the mobile output.

• But if our outputs are online and mobile and mobile has top priority, we may not use features that don’t work in mobile without considering that they do work in online. Ensuring that we consider all the outputs might instead suggest that we create and use popups but still conditionalize them out for the mobile output.

In summary, the question of whether to use popups depends on two things:

• Knowledge of strategic and business issues – what outputs you need, with what priority, and on what devices used in your market.

• Knowledge of technical issues – what microbrowsers or standards are used on your output devices, what help authoring tool features they support, and how those features convert.

It comes down to doing a needs assessment and configuration analysis before starting the project – the same requirements that we’ve always had to deal with but simply taken in a few new directions.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 4

2010-10-13T03:03:00.000-07:00

Next are three related recommendations that have to do with creating content – what we used to call writing…

17. [SUITABLE] – Ensure that content is suitable for use in a mobile environment.

The W3C says “Users in a mobile context are often looking for specific… information, rather than browsing.” This is also true of online material from tech comm., especially online help.

For example, people don’t browse online help; they read it for specific information they need to do some task. But this may not be true of other types of online material. For example, you may create online procedure manuals for use in the field. In such manuals, users might browse the content or read larger chunks than they would in online help because there’s more to know or learn about the subject.

So this recommendation requires analyzing our content in order to determine:

• What parts don’t apply to the mobile output’s functional environment. You’d remove those parts by conditionalizing them out for the mobile output – e.g. single sourcing. For example, information about configuring an application for a printer might be useful in large-screen online format but irrelevant for mobile.

• What parts don’t apply to or aren't crucial for the mobile output’s usage environment – “need-to-know” versus “nice-to-know”. You’d remove the latter from the mobile output by using conditional build tags. For example, you might create an online shopping guide to single malt scotch that showed each brand’s label in the large-screen version. However, while showing the label might still be nice in the mobile output, there isn’t enough room on the screen so you’d decide to hide it and use the space for more appropriate content.

18. [CLARITY] – Use clear and simple language.

This should be a given in tech comm.; write in clear and simple language... The reality is that we often don’t. The passive voice is used by us rather than active voice. We address “the user” rather than “you” and get tied up in gender-neutral writing like “The user... They…” and “he/she…”

If you know your content will be single sourced to mobile devices, change your writing style now to short and simple. If you have a lot of legacy content, this may require more work than you can afford and you may decide to leave the legacy content as is. However, it may be worth a quick look at that legacy content to see if there are any simple writing fixes that offer a quick payoff for a low investment. For example, can you replace the phrase “… enables you to…” with “… lets you…”, as in “This feature enables you to…” with “This feature lets you…” This sounds trivial, eliminating six characters out of the twenty-seven original ones, but consider that that’s a 22% reduction in that one phrase.

I’ll add that if you know you’re heading toward mobile output, consider getting an editor to do traditional tasks like copy-editing in order to shorten and simplify your content for mobile in particular, and any writing in general. If you’re an editor, doing a before-and-after edit might be a way to sell your services to companies that are moving toward mobile output and have large amounts of textual content.

19. [LIMITED] – Limit content to what the user has requested.

This recommendation suggests that content may have to change dynamically in response to user requests. This suggests the presence of a database on the server that reconfigures the content in real-time. That capability is starting to become available for tech comm., currently in AuthorIT’s Aspect product (http://www.author-it.com/index.php?page=aspect), but is still an enterprise-level product and thus not cheap.

To a degree, however, we can limit the content to what user request by making the most rigorous possible use of topic-based authoring – writing the content in small chunks and giving those chunks the clearest possible titles, index entries, search synonyms, and other retrieval mechanisms that our authoring tools support.

In summary, if you’ve written the content tightly, used topic-based authoring rigorously, and identified what content applies to what functional and usage environments, then you should be on track to support single sourcing to mobile. And the points in the previous sentence are simply good writing anyway, mobile or not.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 3

2010-10-05T02:39:00.000-07:00

The next recommendation, again in the order in which I’m getting to them…

6. [NAVBAR] – Provide only minimal navigation at the top of the page.

For years, help authors have used the “tri-pane” window created by Microsoft for HTML Help in 1997. This model, adapted for the web-oriented WebHelp model created by eHelp, original vendor of RoboHelp, in 1998, put the major navigation controls – TOC, index, and search – in a vertical pane at the left side of the help window. It added a horizontal toolbar for the nav function labels and custom functions, as shown below:

The problem with this model on mobile devices is that the tiny window can only show a tiny part of the screen; it can take many (irritating) horizontal and vertical scrolls to get past the toolbar and navigation controls to the actual content. What to do about this?

The W3C suggests “provide basic navigation… on the top of the page… secondary navigational element[s] may be placed at the bottom of the page if really needed… users should be able to see page content once the page has loaded without scrolling.”

This is a perfectly sound recommendation. However, when it comes to HAT-based online documentation or help created using tools like Flare or RoboHelp, the navigation options can use a lot of screen space even without the horizontal toolbar.

A solution implemented by Flare in WebHelp Mobile and RoboHelp in ePub is to revert to the old (pre-HTML) Windows Help model. This output had the content and navigation in separate, single-pane windows, only one of which could display at a time.

For example, start a WebHelp Mobile online document and the navigation pane displays. Select a topic, from the TOC for example, and the content pane replaces the navigation pane. ePub takes a similar approach on the devices I’ve seen. (This may be modifiable in the interface. It’s on my list of things to check.)

Some observations about this model:

• Users can only see content or navigation – not both simultaneously, unlike the tri-pane model that they may have become accustomed to over the years. This may take some getting used to. Not much, but people rarely expect “books” to change their format.

• Flare’s mobile output skin is more limited than its regular skins because there’s less screen space. This is important if you created custom navigation or other buttons for your regular WebHelp output only to find that there isn’t room for them in mobile. Ditto for a RoboHelp project that you output to ePub. (And ePub’s navigational interface is largely fixed.)

• Finally, an example of why you can’t just test your mobile output on emulators. If you output a RoboHelp project to ePub and test it on the ADE (Adobe Digital Editions) reader, you’ll find that ADE uses a left-right split screen model that shows the navigation features on the left and the content on the right. Open the same eBook on a physical device, however, and you’re back to single-pane mode. This may be modifiable through the ePub code, but the need for any custom coding makes the HAT-based output less convenient.

In summary, if you’ve stuck to the basic navigation offered by your HAT, you should be okay when you convert to mobile. But if you’ve created custom features on the navigation pane or toolbar, you may have to re-think your design when you go out to mobile.

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile – Part 2

2010-09-30T10:12:00.000-07:00

Continuing the previous post, here’s the next recommendation…

22. [SCROLLING] – Limit scrolling to one direction, unless secondary scrolling cannot be avoided.

The screens on which we typically display help are large enough to fit almost any graphic or table without forcing users to scroll horizontally as well as vertically. When horizontal (“secondary”) scrolling is needed, it’s rare enough that we can excuse it as an unfortunate exception from our design.

It’s not that simple when we single-source help projects to mobile devices. Mobile device screens are so small that almost any graphic or table might need horizontal scrolling. This is okay technically, but it reduces usability. How to deal with this? Four ideas:

1. Accept it. That wide graphic or table may be necessary to convey the information.

2. Modify it. For a graphic, we may be able to crop out and display small sections of the graphic rather than the whole thing. For a table, we might be able to restructure it in order to narrow it. But modification is iffy, since it runs the risk of losing or confusing the original meaning of the material.

3. Conditionalize it. You may decide that you can live without the graphic or table in mobile output, or that you have to live without it because you can’t modify it to fit on a mobile device screen. You might define a condition called “mobile”, apply it to the graphic or table, and exclude anything conditionalized as “mobile” when you generate the output.

4. Define its size in relative instead of absolute units. Replace points, pixels, or other absolute size units with relative units like % or ems, among others. For example, you might change a graphic’s width from 180 pixels, which may add horizontal scrolling, to 100%. This says that the graphic’s width is 100% of the available space in the window, no matter what the device, and leaves it up to the browser to figure out exactly what that is, including on a mobile device. This approach works but has several quirks.

• It’s easy to shrink a graphic to fit into the space of a mobile device screen but the result may be too small to read. In that case, you might have to conditionalize it out after all. Ditto for tables.

• The graphic may show quirky behavior when inserted into a table and output to ePub format. This happened with an output from a RoboHelp project. I don’t know whether the problem was in the ePub standard itself, the RoboHelp converter, or my project specifically. To be investigated…

More to come…

W3C Mobile Web Best Practices and HAT-Based Mobile

2010-09-27T04:37:00.000-07:00

In the ‘90s and early ‘00s, products like Newton and standards like WAP and CE tried to get mobile computing into the mass market. They all failed due to shortcomings in technology, usability, and interoperability. Never mind largely silly content…

In the early ‘00s, to help give mobile computing another crack at the mass market, the W3C (WorldWide Web Consortium) began an effort called the MWI (Mobile Web Initiative) in order to set technical and best practice standards.

I've followed this effort closely for years – I’ve been working with, training on, and looking for markets for mobile since ’98 (thanks to Joe Welinske, who introduced me to Windows CE in '97) and was the STC’s (Society for Technical Communication) representative to the W3C from ’02 to ’05 so I had a dual interest. But the mobile mass market never went anywhere until Apple brought out the iPhone and sent the market skyrocketing.

A side effect of mobile’s skyrocketing in the mass market has been a slow but steady rise in interest in using mobile for tech comm. Until recently, creating content for mobile, in the form of apps, was so different from “true” tech comm and online help that there was little or no overlap. Tech writers had to do “apps” to get into the mobile space.

That’s changed in the last year, as two well-known help authoring tools (HATs), MadCap Flare and Adobe RoboHelp, added support for mobile output. (There may be others too; I happen to support Flare and RoboHelp so they’re the ones I’ll focus on. But what follows applies to any HAT that offers mobile as an output.)

As part of the MWI, W3C created several standards including Mobile Web Best Practices Basic Guidelines, a Recommendation as of 29 July 2008. (www.w3.ord/TR/mobile-bp/) It offers 60 recommendations for creating, coding, and structuring of content.

It was NOT written with HAT- based mobile in mind, but many of the recommendations do in fact apply to HAT-based mobile, either directly or with some tweaking. Because of that, the rest of this post and a series to follow will examine these recommendations from the point of view of creating HAT-based mobile output. I’ll discuss the recommendations as I get to them, which means I won’t address them in the same order as they appear in the W3C document. But I will use the recommendation numbers for reference. Starting with…

4. [TESTING] – Carry out testing on actual devices as well as emulators.

Testing on emulators is convenient. Passing output to the emulator is built into the HAT’s interface, so it’s a matter of a few mouse clicks. Flare has its WebHelp Mobile emulator, and RoboHelp uses the Adobe Digital Editions (ADE) application as its ePub emulator. Both work fine, but both have the same issues as every other emulator I’ve seen. (In other words, this is not a criticism of either vendor’s emulator but an assessment of emulators in general.)

• They can’t simulate network traffic loads because they’re not on a network, so there’s none of the delays that might occur in the real world.

• They’re driven by the full processing power of the PC on which they’re being run, rather than by the more limited processor and memory of the real mobile device, so they run more quickly and smoothly.

• They may not offer the unique behaviors of the real devices, such as the touch-screen interface, so the user experience isn’t faithful to reality.

• You may also get some odd behaviors in different emulators, even those for the same standard. For example, if you output a RoboHelp project with multiple topics to ePub and display it in ADE, the result displays all the topics in ADE as one long scrolling file – basically a “book”. Display the same output in Firefox using its epub plug-in, however, and each topic from the project displays as a separate web page. This means that you’re going to get different behaviors for things like scrolling – through the whole book versus one topic at a time, for example.

So you’re ultimately going to have to buy examples of each device on which your mobile content is supposed to run and test accordingly. That’s nothing new for Engineering, but it may be a new experience for a doc group. The doc group would either have to set up its own publishing, testing, and QA processes and lab or work very closely with Engineering in a new and unusual way.

More to come…

A Business Side to Tech Comm “Initiatives”

2010-09-16T04:52:00.000-07:00

Changing how a doc group works – new tools, new output formats, a new development methodology, etc. – has long-term strategic effects on the group and its relationship with groups like Engineering or Sales. These effects mean that such changes need to be “sold” – what’s their strategic and financial effect on the overall business? Will they lead to lower costs, higher sales or market share, more efficiency, better regulatory compliance, or some other benefit?

There’s so much information about this business aspect of proposal writing that it can be hard to know where to start. One good starting point that I recently found is a book called Maximizing Project Value by Jeff Berman, from AMACOM (www.amacombooks.org).

The book describes a project proposal methodology called Speed2Value, but the write-up is generically applicable to any project. It focuses on the strategic rather than the tactical, stressing a proposed project’s effect on the company rather than just looking at whether the project was finished on time and on budget.

The book also provides an overview of cost-justification methodologies like ROI (Return on Investment), NPV (Net Present Value), Payback Period, and IRR (Internal Rate of Return). It doesn’t go into a lot of technical detail, just enough to provide a starting point for further research or actually writing a proposal. The book is presented in lay terms, is clearly written, and is a quick read (I read it on a plane between Boston and Phoenix). It’s worth buying.

Why Use Twitter For Tech Comm?

2010-09-16T02:36:00.000-07:00

Excellent blog post on why to use Twitter for tech comm. See http://tinyurl.com/yg3f76p

Thanks to Cheryl Landes for this recommendation.

The Future Arrives Earlier Than Expected

2010-07-27T02:04:00.000-07:00

One sure-fire aspect of writing trends articles is knowing that I’m going to be wrong about something. What’s entertaining is seeing just how quickly that can happen...

In December, 2009, I wrote an article about trends for STC’s Intercom magazine in which I predicted, among other things, “dynamically reconfigurable outputs,” which I described as follows:

“One problem with documentation is our inability to create one output to handle everyone’s needs. We can use conditions to create multiple outputs from one project, but this creates multiple outputs to which we then have to steer readers. It works, but the development is inefficient and can be confusing. Instead, what we need is the ability to create one output that dynamically reconfigures itself based on readers’ login permissions, requests (“Only show me material related to Idaho.”), or external stimuli (like an aircraft maintenance manual whose content varies depending on whether the outside temperature is above or below freezing). This technology will simplify distribution of information by reducing the number of outputs. It would also let us create output that responds to readers’ needs rather to our estimate of their needs.

Assessment – This technology is under development now, but every effort that I know of is still proprietary. I expect it to appear in mainstream tools in the next few years…”

Four months later, at the WritersUA conference in Seattle in March, 2010, I mentioned this idea to a representative of AuthorIT. After he stopped laughing, he said AuthorIT had come up with just such a product in mid-2009 but hadn’t gotten around to serious marketing until WritersUA. So I basically had the prediction right but the timeline badly wrong.

The product is Dynamic Assistance Platform, or DAP, one of whose components is called Aspect. As the AuthorIT site describes it “…The content is personalized for the person viewing it by matching information in the content with their login profile. This means that when a user views content, it is content that has been filtered for their profile…”

From what I got at WritersUA, Aspect may not be for everyone – as an enterprise-level product, its cost may be too high for small doc groups or applications. But it is the first commercial implementation I’ve run across of what sounds like a really useful idea. Even if you use another authoring tool, it’s worth reading about. See http://www.author-it.com/index.php?page=aspect.

Blog About Mobile eLearning

2010-07-05T03:28:00.000-07:00

Interesting blog re mobile, specifically SMS-based, eLearning at http://tinyurl.com/27ag2my.

I agree with the third commenter, Sue Cloud, who argues that the blog is talking about bits of communication rather than true learning per se, but I suppose this is a matter of definition - e.g. if you consider the Tip of the Day that appears when you start an application to be "learning," then this can indeed be considered "learning."

Thanks to Cheryl Landes for this tip.

Questions from Captivate Course in Orlando

2010-06-18T04:47:00.000-07:00

Chris and Anthony,

To delete misspelled terms that you accidentally add to the dictionary - This is mentioned in the help. Terms that you add to the dictionary during a spell-check go into your personal dictionary, userdic.tlx, which you should find at \\Documents and Settings\\Local Settings\Application Data\Adobe\Adobe Captivate\Spelling.

To delete the Adobe logo from the movie playbar - You'll have to use a different skin. To do so, select Project > Skin Editor and select any other skin listed in the Skin field in the upper left corner of the dialog box.

Enjoy...

Workshop – Creating Mobile Device Output Using Flare

2010-06-13T08:24:00.000-07:00

Need to create output to run on mobile devices from a Flare project but not sure how? You could create an app, but the process may be unfamiliar to your developers and call for new tools. Or you could use Flare itself to create the mobile output, in the form of a "site" that should run on most mobile devices that have a microbrowser.

Generating mobile output from a Flare project is simple mechanically. Where things can get tricky is in the design and control of the content – deciding what content to show or not show in mobile form and controlling that, controlling formatting by making full use of possibly unfamiliar CSS features like mediums and relative sizes, and more.

This half-day, hands-on, web-based class is aimed at Flare 6 users who need to quickly get up to speed on converting existing projects to Flare WebHelp Mobile output. Prior experience on at least one Flare project is necessary.

- Date - Monday, July 12, 9 AM to 12:30 PM ET.

- Cost - US$150 per person, includes workbook and working files.

- Location - Remote, via GoToMeeting.

- Outline – see www.hyperword.com/FlareMobile.htm.

Contact Neil Perlin at nperlin@nperlin.cnc.net to register or for information about payment.

Creating Mobile Output with Flare

2010-06-08T05:04:00.000-07:00

New half-day, hands-on workshop on how to convert online help or doc projects created using Flare to mobile format. Covers the conceptual background, conditions, CSS mediums and relative size settings, the mobile skin, and testing.

See http://www.hyperword.com/FlareMobile.htm

First of a series of workshops on mobile and tech comm.

Adobe RoboHelp’s Mobile Output

2010-06-01T11:43:00.000-07:00

Continuing my look at help authoring tool-based mobile output, we turn to RoboHelp 8.

RoboHelp mobile output uses the International Digital Publishing Forum (www.idpf.org) ePub standard. This means the output can run on any device that supports ePub, like the Barnes & Noble Nook, Android devices with ePub readers, Kindles (with some extra work that doesn’t involve RoboHelp – see http://kindleworld.blogspot.com/2009/08/ million-free-google-books-in-epub-for.html) and others.

RoboHelp creates mobile output using a script that you import into RoboHelp itself. (This is similar to how Adobe added AIR support to RoboHelp – using a plug-in in v.7 before adding it to the interface in v.8. If the mobile market takes off, I’d expect to see Adobe follow the same path and build the script into the interface in v.9.)

What follows is an overview of what’s involved mechanically and design-wise in converting a fairly standard project to mobile format. The project is a proof-of-concept I created for a Boston-based maritime historical to which I belonged from 1990 to 2003. Members of the group built museum-class ship models, and my idea was to create an online “book” about the models and have it sold in the museum store as a fund raiser for the group.

Here’s the main screen and default topic:

And here’s a fairly typical topic screen.

The project had a TOC, index, header and footer in one topic, breadcrumb trail, table and graphics, internal links, an external link, popups, and an audio file. My question was how well the project would convert to mobile with no effort on my part.

The first step is to download the ePub generator script and a file archiver, both free. (See Ankur Jain’s blog at http://blogs.adobe.com/techcomm for instructions.) A few caveats – you’ll have to change the name of the script file to ePubGenerator.jsx and modify the script – a minor step into code – to specify where you put the file archiver on your PC. You can then import the script into RoboHelp using the Script Explorer. Finally, you have to change the XML handler using RoboHelp’s XML support feature.

You can then open the project to be converted to mobile format and run the script. After you specify the output folder, RoboHelp will create the ePub output. Here’s the result in Adobe’s ePub viewer – Digital Editions. First the main screen and default topic:

And the topic.

The result? Mechanically, pretty good. Without making any changes to the initial project, here’s what I got…

• Text converted correctly, as expected since ePub offers “reflow” of text. The text also resized correctly when I used the resizing options on the viewer.

• The TOC came across fine.

• Internal jump links worked fine. External jumps worked too, but opened the target pages in a new browser window. This is okay if your users will read the book in a full browser, like Firefox with the ePub reader add-on, but not if users will read it in a “true” reader. Popups did not work, which I assume is because ePub doesn’t support them.

• Graphics seemed to come across fine.

The problems I found seemed to have more to do with apparent incompatibilities between help project features and the ePub standard, and design.

• The index didn’t convert. I’m not sure if this is because ePub doesn’t offer one or because of something that simply hasn’t made it into the conversion script yet.

• The search tab didn’t convert. It was replaced by the ePub viewer’s search tool, as can be seen, with some difficulty in the images above, at the end of the toolbar.

• One oddity – the project apparently converted to one text file when viewed in the Digital Editions viewer but individual topics when viewed in Firefox. I assume there’s a reason for this that I simply haven’t found yet.

• Projects meant to be single sourced to ePub, in addition to any other outputs, need greater and more rigorous use of CSS. Basically, avoid local formatting – good advice under any circumstances.

• Adobe recommends setting sizes as % rather than the usual points. You’ll have to do this for everything, not just text. Also, don’t use hard returns for paragraph or table row separators because these double when rendered in ePub. (Compare the paragraph spacing in the pre- and post-conversion versions of the default topic, and the spacing of the table rows in the pre-and post-conversion versions of the ship topic.) Instead, specify the spacing as part of the style for the items in question.

• There are also some formatting requirements described in Ankur’s April 23 post.

Finally, as you’d expect when converting content from big-screen to little screens, you’ll have to decide what content is “need to know” versus “nice to know,” such as graphics, and be prepared to conditionalize out the latter. You can fit many graphics in the mobile output by making their sizes relative, with the % unit of size, but a graphic may become small enough to be illegible. Think of this as single sourcing taken to an extreme level.

The biggest benefit of this support for mobile output is the fact that it makes it easy to try mobile without buying and learning new software. And, if you don’t like the result or it’s not what you needed, just delete the output, delete the script (or just ignore it), and go back to your regular output.

And, again, it’s challenging and fun to figure out how to output to mobile…

Upcoming mlearning (Mobile Learning) Conference

2010-05-28T05:34:00.000-07:00

mLearnCon, a mlearning (mobile learning) conference in San Diego June 15-17:

http://www.elearningguild.com/mLearnCon/content/1603/mlearncon---home

Thanks to Cheryl Landes

Interesting Review of the iPad in Time Magazine

2010-05-27T08:06:00.000-07:00

Here's the link - www.time.com/time/business/article/0,8599,1976932,00.html

Thanks to Deb Sauer, Deborah Sauer Consulting

TE SIG Mobile Content Session - Demos via GoToMeeting

2010-05-26T05:13:00.000-07:00

As I said at the TE SIG meeting last night after my laptop wouldn't sync up to the projector, I'm going to show the live demos of various authoring tools and emulators via my GoToMeeting account instead.

In order to try to take people's schedules into account, I'm going to run the demo twice in 45 minutes sessions on the following days:

Wednesday, June 2, from 9 to 9:45.
Friday, June 4, from 1 to 1:45.

If you can make either of these sessions, email me at nperlin@nperlin.cnc.net and I'll send you the meeting ID. If you can't make either of these sessions, let me know at the same email and we'll try to work something out.

MadCap Flare Goes Mobile

2010-05-21T05:39:00.000-07:00

In a recent post, I discussed how RoboHelp 8 has added support for mobile output. In this post, I’ll look at Flare 6 and its support for mobile output. Again, some background about the mobile space…

Mobile debuted in the early ‘90s with Apple’s Newton. Newton was revolutionary, but its problems turned it into a footnote in computer history. Windows CE Help and Wireless Markup Language followed several years later, but failed in the mass market for, in my opinion, three reasons. One was an unattractive output, shown below in a real screen from a presentation that I gave in 1998:

That problem has been corrected, as evidenced by the examples below – iPhone apps for star charting and birding:

Another problem was that vendors didn’t know what content to offer so they offered anything, much of it “fluffy” novelties whose charm wore off quickly and that lacked staying power for the mass market. Many apps today share that problem, but there are a lot more apps so there’s a better chance of finding something good amid the fluff.

The third problem in ‘98 was a rough authoring environment, often requiring hand coding. Authoring can still be difficult, but there’s a decade’s worth of improvement in the tools.

So, in general, mobile has become easier to create and more attractive to use.

For today’s technical communicators, there’s a new problem however. Do we create apps, or help or doc to be read on mobile devices? App development is new for many technical communicators and can take them into unfamiliarly complex authoring issues. But the help authoring tools, or HATs, offer another approach – letting us put online content into a format that works on mobile devices and either stands on its own, like an online procedure manual for use in the field, or help for a real mobile app. (If you think today’s mobile apps are so simple as to need little or no help, you’re right. But as mobile device power keeps increasing, I expect increasingly powerful apps to appear that will need help.)

Flare offered mobile output as an option in the interface when it released v. 6 in March. In this post, I’ll give an overview of the feature set and results. Another article will appear in a forthcoming issue of the Communicator, the journal of the ISTC (Institute of Scientific and Technical Communications) at www.istc.org.uk.

Flare 6 supports mobile output through its WebHelp Mobile output target. The target is integrated into the Flare interface, so using it mechanically simply involves creating the target, selecting WebHelp Mobile as the output type, setting or selecting various options, and generating the output. Most of the options are familiar ones in Flare, such as skins, TOCs, CSS mediums, and so on.

How well does it work? Here’s my test project, output as standard WebHelp:

And here’s the same project output in mobile form:

What’s striking about this test is that I made no changes to the project except for the skin settings; Flare just gave me the material in a different format. This has strategic effects for development. If you’ve wondered what your online help or doc would look like in mobile form, you no longer have to buy and learn new tools. Instead, just select mobile as the target. And if mobile proves not to be what you need, just delete the mobile target and try something else. In other words, there’s no risk to trying mobile.

More specifically:

• WebHelp Mobile produces a “mobile site” rather than a “mobile app” so it’s not tied to a specific device. It’s simply a web site accessible from any device with a microbrowser.

• The code is “pared-down” XHTML, so it’s open-source.

• WebHelp Mobile automatically adjusts to a microbrowser’s features. For example – no JavaScript support means no search capability or dynamic text features. This automatic adaption to the microbrowser’s capabilities simplifies project planning, design, and management.

• Flare has pre-defined mobile skins, so skin definition is just point-and-click.

• There’s a generic emulator to preview WebHelp Mobile, shown below:

• All standard navigation options are available on the home page, as shown below.

Mechanically, outputting a project to mobile is a snap. The problems arise in design. This isn’t a problem in Flare but rather in the need to fit output designed for large-screens onto a screen the size of a sticky note. My test project has a fairly typical feature set. Here’s a summary of what happened on conversion…

• Text and variables (which are text) converted smoothly because they reflow to fit the screen sizes.

• Objects that are too big converted but added horizontal and/or vertical scrolling. (Scrolling reduces usability but isn’t necessarily evil, but avoid combining both types of scrolling at the same time if you can.) You can expect this problem with tables, graphics, drop-downs and togglers that contain tables or graphics, master pages, wide head styles, and SWFs. Snippets and project import link items can also be troublesome because they may have the same problems but you won’t “see” it as you insert them – basically “out of sight, out of mind.”

• Popup links converted to jumps. Some microbrowsers don’t display popups, so making the popups work as jumps supports the lowest common denominator microbrowser.

• The only other problems I’ve found or heard about so far are due to the limitations of the display devices themselves. For example, WebHelp Mobile should be able to use a regular project’s header and alias files to create context-sensitive help for mobile apps, but the device must support multitasking or else opening the help closes the app.

• Finally, there’s the design problem of deciding what information to omit from the mobile output.

Except for the last point, you can deal with most of the other problems by making fuller use of Flare features. For example, style properties should be relative rather than absolute – % or ems for text size instead of points for example. This isn’t unusual for text, but what may be unusual is the need to do so for tables and images. (You’ll want to create a CSS medium for the mobile output.) For example, here are two versions of the same page, one with the graphic displaying at its default size and the other with the height and width set to 50%. Note how the second one eliminated the horizontal scroll bar.

This isn’t that difficult, but it will require you to look more closely at your styles and properties and maybe try some features of the Stylesheet Editor that you’ve ignored until now. You’ll also make greater use of conditionality, and perhaps variables in order to use full names in the regular output but abbreviations in mobile. You may also have to re-evaluate your content to determine what’s really needed and what’s there because it’s cool and you had the screen space to indulge yourself. And so on…

If you’re a Flare shop and considering mobile output, you’ll find that the mobile target will push you into new areas of information design in general and Flare’s feature set in particular. And it’s fun…

Open Questions From Single Sourcing Class in Canada on May 13

2010-05-18T12:47:00.000-07:00

Here are the answers to the open questions from the Single Sourcing class in Scarborough last Thursday, May 13

In what format does Flare output PDF – Adobe.

Do mathematical expressions convert correctly – Depends on the version of Acrobat you have. Check your version's specs.

Do custom templates have to be in the My Documents/My Templates folder – Yes in Flare through v.5. V.6 now lets you put templates wherever you want by using the Template Manager dialog box, available by clicking the Manage Templates icon on most Add New… dialog boxes.

Can you physically exclude topic files (.htm) from the output folder – Conditionalize the topic at the topic level, not at the content level in the topic, and then exclude the condition from the build to physically remove the topic’s .htm file from the output folder. This did NOT work the first time I tried it, but it did when I tried it twice more so I assume I missed a setting the first time.

Can you have topics’ content output to print without listing the topic in the TOC in Flare – No. Flare uses the TOC to select and sequence the topics to output to print, so removing a topic from the TOC in Flare removes that topic’s content from the output. You can work around this by leaving the topic in the Flare TOC for output to Word, then removing the topic’s content from the TOC in Word.

Thanks to Alvaro in tech support for several of these answers...

May 25th Boston STC SIG Meeting on Mobility and Tech Comm

2010-05-12T13:03:00.000-07:00

This is a reminder about the Technical Editing SIG presentation that I’m doing for the Boston chapter of the STC on May 25 in Natick, MA. (See the chapter site for the address, times, and directions - www.stcboston.org/sigs/te_sig_may2510.shtml.)

I’ll start by discussing the rationale for mobile content, and for tech comm to be creating that content as part of our regular role. Then the history of mobile, briefly – one slide, followed by three reasons why mobile information may succeed this time.

I’ll then cover three target options, two architecture options, and two dev options, with the dev options focusing on using HATs like Flare or RoboHelp to create mobile content vs. using dedicated mobile web authoring tools. Finally, I’ll look at what standard online content design elements work or don't work in the HAT-created content and how we’ll have to change some ways in which we work in order to fix those things and add mobile to our repertoire.

I’ll also demonstrate a number of readers and emulators including, at the moment but not officially, MadCap’s WebHelp Mobile viewer with content from Flare 6, Adobe’s Digital Editions ePub emulator with content from RoboHelp 8, an Android emulator, a quasi iPhone emulator, Firefox in small-screen rendering mode, and whatever other tools I can set up between now and the 25th.

And if you're interested but can’t make it, email me and I’ll send you the slides.

This stuff is fascinating...

The Return of Location-Based eCommerce

2010-05-10T04:09:00.000-07:00

One benefit of longetivity in any field is the ability to see cycles. The latest cycle I’ve seen is the return of location-based eCommerce – an interesting idea (just as it was ten years ago).

Consider an article entitled Social Media’s New Mantra: Location, Location, Location in the May 10-16, 2010 edition of Bloomberg Business Week. The article discusses the promise of social media-based, location-based ecommerce. It focuses on several companies that are moving into this space or that already have a presence, ranging from startups to existing companies. The article suggests the example of an iPhone app that checks your friends’ calendars to see if they’re free for the evening, suggests a restaurant that everyone’s wanted to try, notes table availability, and notes where your friends are to make it easy to hook up. Cool…

Now consider this description...

… there’s a specific type of location-based application that’s likely to affect technical communicators – lCommerce (“l” for Location), or mCommerce (“m” for Mobile)… these applications will determine your location and try to sell you things based on that location. For example…

• The florist’s site beeps you when you’re within a mile of the store to remind you that tomorrow is Mother’s Day.

• The car wash beeps you as you drive by on the day after a blizzard to remind you that road salt is bad for your car’s chassis – why not come in right now?

• You’re looking for a Cajun restaurant in an unfamiliar city, find one on an online restaurant list, select it, and have a web site detect your location and continuously provide directions to the restaurant

More ambitious applications could bring people together by detecting their relative locations. For example, a Starbucks’ site might call as you drive past and tell you that your friend Bob is inside and that you’ll get a dollar off a latte if you drop in now. Or that florist’s site might beep to tell you that tomorrow is Mother’s Day but warn you that your mother is in the store right now.

This latter description is from a column that I wrote for Intercom, the magazine of the Society for Technical Communication, in February 2001. I ended that column with this prediction as to how location-based apps might affect technical communicators.

… should see two types of work coming out of the location-based applications. First, there’s likely to be an increase in site development work as local businesses decide to create web sites. Second, given the high potential for irritation…, we may find work creating filters to block calls from the same sites that we created. If all this sounds unlikely, remember that it isn’t too long ago that the idea of technical writers creating web sites was ridiculous. Location-based applications will be an interesting addition to our repertoires.

I’d have to say that I got this prediction wrong. (There may be technical communicators out there who do this type of work, but I’ve never met one.) However, as society becomes increasingly mobile, the idea is still sound and the technology is a lot better than it was in 2001. I have no idea what might come of this technology, but it is worth watching.

RoboHelp Goes Mobile

2010-05-06T12:38:00.000-07:00

Help authoring tools, or HATs, have been around for a long time. RoboHelp, the second oldest HAT, appeared in 1991/92 – impressive longetivity in a technical field.

HATs stay alive (business issues aside) by constant adaptation in the face of technical changes. For example, HATs in general could have disappeared in 1997 when Microsoft introduced HTML Help, since we could now create online help with web authoring tools like Dreamweaver. Many of the original HATs did in fact fail to make the shift to HTML and disappeared. But the larger, better funded ones like RoboHelp and Doc-To-Help did make the shift and are with us today.

That large-scale adaptation has continued since 1997, with the incorporation of support for PDF, XML, DITA, and now, mobile output, the focus of this post.

The mobile space has been chaotic since the late 1990s. Technologies like Windows CE Help and Wireless Markup Language looked good but failed to penetrate the mass market for several reasons, a major one being the fact that mobile output looked like this in 1998 (a screen from a Wireless Markup Language presentation that I gave back then):

This was a simple mobile app designed to teach the coding, but full-scale apps weren’t all that much more exciting. The screens were grey and bland compared to what we expect today, which looks more like this…

So mobile content and mobile apps are more inviting than they were a decade ago. And the explosive growth of the iPhone, Android, RIM, and other mobile devices has given mobile a degree of market credibility that it hasn’t had before. So it makes sense to start looking at mobile. And yet…

Many companies are reluctant to try mobile for three reasons:

• There may not appear to be any environments in which their apps can be used in a mobile mode. But some uses just may not be immediately obvious. For example, accounting apps might be used in the field for inventory control and need mobile-style online help. Or reference guides containing settings for pollution sensors in a food processing plant might be more usable on a mobile device when the sensors are mounted up near the ceilings.

• Companies may be looking at the market for mobile apps or help or “content” and find the choice between the various platforms to be too confusing or chaotic to be able to pick one.

• Companies may have tried mobile before and been disappointed by the feature set or burned by the reception in the market.

In each of these cases, companies will be rationally reluctant to invest in new tools. But if your company uses certain HATs, and I’ll focus on RoboHelp here, there is a way to test the mobile waters almost effortlessly.

On April 23, Adobe released a RoboHelp 8 script that converts RoboHelp projects to the ePub format. ePub is a standard from the IDPF (International Digital Publishing Forum) for “reflowable” text, which essentially means that content can change its width to take into account the width of the screen on which it’s being displayed. You can find the instructions for downloading and installing the script, along with suggested best practices for coding content, on the blog of Ankur Jain, RoboHelp Product Manager, at Adobe’s Technical Communication blog at http://blogs.adobe.com/techcomm/. The instructions for the script itself are in the April 23 post. The preliminary announcement was in the April 12 post.

The reason this script release is important is that it’s strategic. If you’re a RoboHelp shop but have wanted to try mobile output, you no longer have to buy and learn new authoring tools. Instead, mobile simply becomes one more output in a tool you already own. And if mobile turns out not to be what you need, there’s no money wasted on a dead-end tool - just abandon the mobile output and go back to your regular RoboHelp work.

I’ll be describing the feature set and some test results in an upcoming post.

2010-04-12T02:41:00.000-07:00

"Beyond the Bleeding Edge" Returns

The "Bleeding Edge" returns to the STC Summit after a three year absence. If you're not familiar with the Bleeding Edge, it's a one- or two- session track in which speakers have 20 minutes to cover topics that appeared after the formal conference schedule was firmed up or just didn't fit into the formal conference presentation categories.

There will be one session this year, from 8 to 9:15 AM on Wednesday, with the following subjects and speakers:

iPhone, iPad, Android: A Quick Intro to Developing UA for Mobile Apps – Joe Welinske, WritersUA

Joe Welinske is currently working on the design of Help for iPhone, iPad and Android applications. While many mobile apps are simplistic, there is a rapidly growing list of applications with robust capabilities. Many of the more robust apps work in concert with web-based applications and knowledgebases. Joe's focus is on exposing the users to features that are not easily discovered. He is also improving user interface text. Word choices are extremely important with minimal screen real estate. In this session you will be exposed to the underlying iPhone and Android development environment. This brief overview can provide you with the basic tools to get started with mobile UA on your own or with your team.

Re-purposing Software You Already Have - An Example Using Mimic - Gretchen Hambright

What can one do with no money and a client who wants a new type of training?With only their brains and a spunky attitude, learn how the TetraTechAMT Training Team used MadCap Mimic to overcome this hurdle and create a new learning system to help make the skies over Washington, DC a safer place.

Search Engine Optimization: My Life with Spiders – Robert Armstrong

In this brief introduction to the world of Search Engine Optimization, we’ll lift the cover off the online marketing world and expose common practices that Technical Communicators should know about. We will discuss ways these practices can be adopted in the documentation world to improve content continuity, publication relevance, and even open doors to new career opportunities.

Hope to see you there...

2010-03-18T06:54:00.000-07:00

March 17 STC IDL SIG Tools Webinar - Notes and Answers to Questions

This post contains answers to questions that I received during my portion of the webinar, and some related notes. Some of the questions that came in apply to several of the tools that were presented so, if I missed your question, feel free to get in touch.

From KB:

Q: I will look the book up. Do you know if Adobe have a user's group for Captivate?
A: Yes – see http://forums.adobe.com/community/adobe_captivate

Q: is there a way to add a TOC into Captivate?
A: Yes, for an individual movie through the skin editor and for a group of movies through the aggregator.

Q: I found that the online captivate training is a little lacking. Can you recommend a good book to purchase to learn Captivate 4?
A: Look on Amazon for the books by Brenda Huettner and Kevin Siegel.

Q: Would like more on Captivate. Maybe another longer seminar with just Neil. A session dedicated to best practices on questions in Captivate would be a suggestion.
A: Something might be arranged thru the SIG at a later date, but that wouldn’t be for a while. In the meantime, if you’re near Philadelphia, I’m doing a half-day Captivate 4 workshop for them at their annual conference next Saturday - http://www.stcpmc.org/index.php?section=66. I’m doing the same half-day workshop again at the annual conference in Dallas, and a regular session on Captivate as well. If you can’t get to any of those sessions, email me offline and we can look at other options.

From MA:

Q: Would you quickly run through the differences between version 3 and 4?
A: The main changes, IMO, are the addition of a “review” output based on AIR that lets reviewers comment electronically, project templates as a part of the app itself, variables, customization via “advanced actions” and Flash-based “widgets”, movie tables of contents, multi-movie tables of contents created the aggregator which replaces the old MenuBuilder. Take a look at the Captivate 4 page on the Adobe site for a complete listing.

Q: I have trouble getting true video files to play within the Captivate movie once it's published & moved to a different location (intranet)--can you speak to that?
A: I’d need to know more about the types of video files you’re using – “true video” – before I could take a stab at this. Feel free to email offline if you’d like.

Q: Can you speak more about the "game" usage?
A: Basically, introducing an element of play to the learning process. Beyond that, I’d need to know a bit more about what you’re thinking of.

From LS:

Q: Can we see a question slide inserted?
A: Done. LMK if you had any questions about what I did.

From JR:

Q: Will any of these publish to Silverlight, WMV or other Microsoft formats?
A: Captivate will not. MadCap Mimic will publish to Silverlight, and I think Camtasia will also but you’d have to verify that on the TechSmith site.

Again, feel free to email offline if necessary.

2010-03-10T04:38:00.000-08:00

Thoughts on “Context-Sensitivity” and Dynamic Output Reconfiguration

I wrote the 2010 trends article for STC Intercom magazine. One of my predictions there was the emergence of “dynamically reconfigurable output,” which I took from an item in the News Digest section of an issue of ComputerWorld from around 2005. That item’s take was that XML, and xMetal in particular, could let us do cool things, such as creating online information that was sensitive to its “context.”

If you’re in tech comm, you may have been doing context sensitive online help systems – that know where you are in the application and display only relevant information – so what’s the big deal? But that wasn’t the idea of the item in ComputerWorld.

The idea there was online information that changed depending on its context, the example being an aircraft service manual whose content changed automatically based on whether the temperature was above or below freezing. (So this manual served two “audiences”.) Or consider smart phone and mobile device apps whose display mode shifts from portrait to landscape automatically, depending on whether the device is horizontal or vertical. (So this manual also serves two “audiences”.)

From tech comm’s perspective, this idea of “context sensitivity” has two interesting angles.

First is simply the idea that “context” means different things to different people and we in tech comm can no longer take that meaning for granted. (The article Context Matters by Beth Schultz, in the September 21/28 2009 issue of ComputerWorld, discussed “context” as the tagging of equipment in a hospital to define its location and make it easier to find. Anyone hired to do “context sensitive help” for that hospital who assumed the standard meaning of “context sensitive” would run the risk of creating the wrong project.)

Second, and odder, is the idea of dynamic reconfiguration as a means of serving different audiences, like below-/above-freezing or horizontal/vertical in the examples above. Such situations are easy to handle using today’s help authoring tools – create one project and, using conditionality and other single sourcing features, generate one version of the output for each audience. We then leave it to some other mechanism to direct users to the right version of the help depending on the circumstances – temperature, physical orientation, etc.

The problem with the multi-output approach is that it’s cumber- some. We have to create one output per audience, which can become challenging as the number of outputs grows. Better to create one output that can modify itself.

We’re slowly heading there. Mark Logic ran a webinar in October 2009 entitled “Dynamic Delivery Is Where It’s At: Custom Documentation From Multiple Formats” that offered some possibilities. And I’ve been told about various proprietary, code-level experiments in online help authoring. I’m just not aware of any developments at the help authoring tool level yet.

If you’re aware of any work on dynamic output reconfiguration using help authoring tools or as proprietary, code-level experiments that can be discussed, I’d love to hear about them on general principles, or possibly as an Intercom column or, if you can get to me between before March 19, possibly as a proposal for the Beyond the Bleeding Edge session at the annual STC conference.

2010-03-04T03:57:00.000-08:00

“Beyond the Bleeding Edge” is Back, and Looking for Proposals!

(for STC's annual Tech Comm Summit (aka annual conference) in Dallas, May 2 to 5.)

Sometime between now and May of 2010, might you…

…develop one online document conditionalized to be viewed on a desktop PC and an iPhone?

…create a document containing dynamically customizable content?

…create a hybrid document?

…perform a hard-dollar cost-justification of your documentation group’s work?

…or do something else that’s bleeding edge, and applicable to technical communication?

Many technical communicators are hard-put to keep up with the daily grind, let alone have time to look into emerging technologies. “Beyond the Bleeding Edge”, which debuted at the 1999 annual conference, addresses this by presenting summaries of technologies and methodologies that are too new or unusual to make it into traditional Summit sessions. After a three year hiatus, “Beyond the Bleeding Edge” is back and looking for presenters for the Tech Comm Summit in Dallas.

Is there a technology or methodology that you’d like to discuss? It can be:

· New… Are you creating online help that can change its contents depending on the outside air temperature?

· Existing, but fairly new to technical communicators, like physical context-sensitivity for mobile devices.

To be accepted, a “Bleeding Edge” topic must be fairly new as of early 2010. A “Bleeding Edge” presentation should be:

· Short – You’ll have about 20 minutes to cover your topic and take questions.
· Informal – Attendees prefer handouts but this is at your discretion.
· Level-appropriate – You can cover a topic at whatever technical level you consider necessary as long as you warn attendees what to expect.

If you enjoy new topics and like to discuss them, we want to hear from you. Send your proposals to Neil Perlin, Hyper/Word Services, nperlin@nperlin.cnc.net or 978-657-5464 by March 19, 2010. There are only three slots this year, on Wednesday, May 5, from 8 to 9:15 AM. Slots fill up quickly, so don’t delay!

2010-01-29T11:36:00.001-08:00

Question About DITA Topics Created Using Flare 5

At my DITAbug presentation on Wednesday night, I was asked whether DITA topics created in Flare by exporting Flare's native XHTML to DITA were well-formed or valid. This proved to be a fairly unusual question and it took several phone calls to track down the answer.

The answer, with one caveat, is that the DITA files should be valid per the OASIS DITA DTD. If they are not, there's a bug and the problem should be reported to MadCap. The caveat is that Flare 5 does not support specializations.

An Addition to the Previous Post...

2010-01-20T05:30:00.000-08:00

I Forgot...

A tip of the hat to Alvaro in MadCap tech support for clearing up a point about the style properties groups. Thanks...

2010-01-20T04:06:00.000-08:00

Notes about Flare’s Style Sheet Editor

Flare’s style sheet editor is very powerful but has several attributes that can be confusing.

One such attribute is the variety of styles, including unusual ones like "generic pseudo-class". Another such attribute is the many properties available for those styles. Another is the combining of the properties into functional groups like Font, Background, or Block, which means that a property can appear in several groups.

This last attribute raises two questions – what do the different functional property groups do? And, if a property appears in several groups, is it the same property each time?

I’ve heard these questions often but never got around to writing anything about them until getting a question (thanks, Jennifer) in a CSS course that I recently taught for MadCap. The question was – “I don't understand the difference between padding in the Box, Cell, and Padding groups in Flare’s stylesheet editor.”

As noted above, MadCap combined many style properties into groups depending on their function. This means that some properties, like Padding, will show up in multiple groups because padding applies to different functions, like paragraph and table cell formatting.

Are the repeated properties simply the same property used in several places? To check, you can list all the properties using the Show: Alphabetical List option on the style sheet editor’s toolbar. If a repeated property is actually the same property, it will show up once in the alphabetical list, exactly what happens with the Padding properties.

Regarding the three functional groups in the question above – Box, Cell, and Padding:

- If you want to format a table cell, use the Cell or Box group properties.

- If you want to format a text paragraph, use the Box or Padding group properties.

Each case, table cell or text paragraph, can be handled by the properties in either of two functional groups, so you'd choose between those groups by finding the one that offered the specific properties you needed. For example, if you want to format a table cell and need to set the margin, select from the Box group. If you didn’t need to set the margin, you could select from either group.

2010-01-15T04:33:00.000-08:00

Some Thoughts about “User-Generated Content”

These days, the term “user-generated content” is usually interpreted as content generated by users via mechanisms like blogs, wikis, Twitter, etc. But there’s another way to view the term that I’ve run into recently – content generated by SMEs (subject matter experts) via Word (can also be Frame), to be automatically turned into online help using a tool like Flare or RoboHelp. In other words, an online help project in which the SMEs do the work, with little need for an online help developer after the initial project setup. I’ve run into two such cases in the last three months, both involving Flare.

Both clients wanted to take material written in Word by SMEs and convert it to WebHelp help format. The material changed often – daily in one case – and passing it through a Flare developer was a potential bottleneck. So the idea was to buy Flare and set up the project using the auto-reimport feature. When it was time to generate the output, this feature would check the imported Word file to see if there was a later version and, if so, reimport the new version and regenerate the WebHelp. Could this work?

The answer is yes, with one big caveat. Reimporting the Word file overwrites the results of the previous import. This isn’t a bug; it’s just the nature of a reimport. But the result is that, until the vendors change how their reimport feature works, it means that SMEs can only use features that they can add in Word. Flare-specific features won’t work, and Flare simply becomes an output generator. Why?

Let’s say you import a Word file into Flare and, by breaking the file at the level 1 heads, wind up with ten topics. You then add Flare-specific features, such as links or index entries, to those ten topics, and clean up any bad formatting that crept into the Word file. As it often does…

The problem is that the next time you reimport that Word file into Flare and wind up with new versions of those ten topics, the new topics overwrite those from the prior import and all your Flare-specific features and formatting corrections will be gone. You’ll have to recreate them. This usually isn’t hard, but it’s time-consuming and reduces the automated component of the publishing that the client wanted in the first place. According to MadCap tech support, there’s no workaround to this problem. The nature of a reimport is that it over-writes the topics created in the prior import, period.

So this issue has at least two ramifications if you’re looking for a way to automate the process of creating online help.

First, because the reimport overwrites the topics in Flare and any Flare-specific features added to those topics, all the writing, formatting, linking, indexing, etc. must be done in Word since that’s the only way to guarantee that those features won’t be overwritten. In effect, Flare becomes an output generator rather than an authoring tool.

Second, the overwrite of the topics also means that formatting corrections that you made to the Word file prior to importing it into Flare will be lost; you’ll have to make those corrections again on the next reimport pass. For example, if an SME used local formatting on a table and you had to fix that formatting to get the table to display correctly online, you’ll have to fix that formatting again on the next reimport pass. The only solution to this problem, and it’s far from foolproof, is to get the SMEs to use Word correctly, or at least less incorrectly. Provide them with Word templates, sell them on the idea of using the templates, and teach them how to use the templates correctly.

2009-10-12T09:11:00.000-07:00

RoboHelp 8 and DITA

If you use RoboHelp 8, you can start getting your feet wet with DITA without necessarily buying a DITA authoring tool. You can’t create DITA maps or topics – that capability won’t be available until, presumably, RoboHelp 9. But you can import DITA maps and topics into RoboHelp 8 to see how well it handles DITA features and how well it turns the DITA material into outputs like WebHelp.

The sticking point is that RoboHelp 8 uses the DITA Open Toolkit (OT) to import DITA material. This means you need the properly configured OT on your PC. If you typically work in RoboHelp’s GUI, installing and configuring the OT will be far more techie than you’re used to. The instructions below should help make the process easier. (Note that some version numbers may have changed since I wrote this. In particular, v. 1.4.3 may have been replaced by v. 1.5.)

Download and unzip the OT from:

http://sourceforge.net/projects/dita-ot/files/#

This will create, among other things, a folder called doc that contains the installation instructions.

Then, if you’re a Windows user, follow the instructions at:

C:\ditaot\DITA-OT 1.4.3\doc\ installguide\windows_installing.html

A crucial step is to be sure your environment variables are correct. You’ll know if they aren’t if you try to import a DITA map into RoboHelp and get this message (shortened somewhat here) in RoboHelp’s Output View pane:

C:\DITA-OT1.5\build_preprocess.xml:269: java.lang.VerifyError: (class: topicpull, method: …
...
Inconsistent stack height 1 != 0

Again, this probably means your environment variables aren’t set correctly. To fix them, follow the instructions in the document at:

C:\ditaot\DITA-OT 1.4.3\doc\installguide\ windows_settingenvvariables.html

However, be aware that some of the settings needed for your PC, particularly the JAVA_HOME setting for the folder where you installed the JDK, may differ from those in the setup instructions.

Note also that some environment variables are optional. For example, if you do not plan to output JavaHelp, you can ignore the JHHOME setting. If you do not plan to use the Apache FOP, you can ignore that setting for the CLASSPATH variable. Ditto for the Xalan setting for the CLASSPATH variable.

Note also that some of these settings are long and complex enough that you do not want to type them if you can avoid it. An easier thing to do is to open the environment variable instructions file (… windows_settingenvvariables.html), copy the value of each variable field that you’re modifying and paste it into Notepad, copy the value to be added for that field from the instructions in the …windows_settingenvvariables.html file, and paste it into the code in Notepad, and finally copy the code out of Notepad and paste it into the appropriate variable field. As messy as this sounds at first, it’s actually straightforward with less risk of typographic errors.

Finally, note that I'm not getting into the specifics of variable settings, especially for the JDK, since it will vary depending on which version you have. But email me if you have specific questions and I'll try to answer them.

You’ll know that you’ve set all the environment variables correctly if you try to import a DITA map and get the “import successful” message in RoboHelp’s Output View pane.

How long will this take? If you’re accustomed to commonly working at this level of technical detail, about an hour. If you’re not, plan on two to three hours. This may be a big chunk of time in a crowded schedule, but it’s a small investment in time that can open up a whole new feature set in RoboHelp.

If you’re interested in more information about how help authoring tools (HATs) are starting to support DITA, I’m giving two presentations at Lavacon in New Orleans in late October, one on how to use HATs to work with DITA and one on how to use HATs to create simulated CMSs. If you’re not going to Lavacon, I’d be happy to send you copies of the PowerPoint slides after October 30.

2009-09-09T03:50:00.000-07:00

A Potential Problem Importing RoboHelp HTML 8 Projects Into Flare 5

Flare’s Import Project feature (File > Import Project) can pretty easily import RoboHelp HTML projects except, in some cases, projects from RoboHelp HTML 8 (hereafter RH 8). One such case may be if you moved an old RH for Word project into RH 8 and then decide to move it to Flare. You may find that some topic files in the project contain RH-specific XML processing instructions that look like this:

If you try to import a project whose files contain these codes into Flare using the Import Project feature, Flare will display an error message for each file that contains such codes and not import those files.

To import those files using the Import Project feature, you first have to open each file in Notepad and delete the entire processing instruction code. You can then import the project, and those files, into Flare using the Import Project feature.

Deleting these processing instructions is easy but tedious because the code may appear in several places in each file, with different syntax, so you have to find and delete each one individually. The differing syntax and multiple lines of code make it hard to reliably use large-scale search-and-replace.

The best solution is probably to wait until MadCap modifies Flare’s Import Project parser to handle RH HTML 8 in a later release. But if you can’t wait, there is a workaround…

Start a new project in Flare and just import the topic files into the project like any HTML or XHTML file. The files will come in, but will show the processing instruction codes when you view the topics in Flare’s XML Editor. Fortunately, users won’t see them in the output. They’re just visually intrusive to us, the authors, while we edit the topics, so we can either delete the codes or just ignore them.

2009-08-10T02:46:00.000-07:00

Remaining Questions From the Captivate 4 STC Webinar

From Peter I – How… set Captivate closed captioning to "ON" by default? – The easiest way I found to do this is from http://www.raisingaimee.co.uk/index.php?option=com_content&task=view&id=35&Itemid=28. Thanks to Captiv8r for pointing this out on Adobe's Captivate forum at http://forums.adobe.com/message/153596#153596

From Judith S - Does Captivate 4 capture right-mouse clicks? – Yes, but it has a few quirks and can vary depending on the version of ActionScript. See this thread on the forum - http://forums.adobe.com/message/2058434#2058434.

From Debora G - …published captivate files are of poor quality (fuzzy text and background image) - how can we improve the quality? When we preview in CP it looks crisp – Did you insert the image as a bitmap (GIF, JPG, or PNG) and have you scaled the movie? Let me know by email offline.

From Linda K - is there a way to correct typos made during capture so they're not repeated in the output? – Per Peter I – “One can replace the original typing with animated typing text.” Is that what you need?

From Linda K - when should we use auto recording mode vs full motion recording? – Basically, use auto mode to record standard movies and fmr to record movies that show continuous visual change like drag and drop or, on the more unusual side, something like the view through an electron microscope. Note that you can start recording in auto mode and switch in and out of fmr as necessary by pressing F9 to enter fmr mode and F10 to return to normal.

From Linda K – how… control the size of the frame in the SWF output? – This question may be referring to two things, so I may not be answering the right one. Read this thread on the forum - http://forums.adobe.com/message/718082#718082 – and let me know if that’s NOT what you were referring to, in which case we can talk a bit more offline.

From Linda K - how do we remove the Captivate branding from the... player? – If you’re referring to the Adobe Captivate “button” from the playbar, open the skin editor (Project > Skin Editor), select the Playback Control tab, open the Playbar field pulldown, and select any playbar style other than default.

From Judith S - Can you demo or show us the aggregator? – Are you asking in terms of how it works compared to MenuBuilder or just in general? Shoot me an email offline if you have a chance.

From Judith S - How easy is it to translate… Captivate movies from English to another language? – I’ve done little translation work so this response may not be complete, and I ask anyone who has translated to extend or correct what I say next... It seems fairly straightforward - pick the desired language for the auto-captions and modify the text as necessary, translate your text captions, and re-do any voiceovers (obviously). You may also have to re-shoot any screens in the appropriate foreign language version of your software. Also watch for culturally-based issues. One example that I ran into years ago was the use of a rural post box icon as an email icon, only to find that many people outside the US didn’t know what it was.

From Jeff F - …explain more about widgets? – There’s a pretty good write-up on them in Captivate 4’s help, but email me if you’re looking for more than what’s there and we can discuss it.

Enjoy the tool...

2009-08-09T04:07:00.001-07:00

Attendee Questions From My Captivate 4 STC Webinar Last Week

Thank you all for your questions. Here's the first set of responses. Look for the rest over the next few days...

From Cynthia K - file sizes for the two examples you showed - The SWF for the Decimal-Binary Conversion movie was 249K. The SWF for the diaper-changing movie was 2.45 Megs.

From Michael M – …interactivity capabilities of Camtasia vs Captivate? – Overall, I’d say they’re similar. They're both major commercial tools, which usually means they support the same overall set of features and differ in specific areas or capabilities – e.g. they both offer text caption boxes, for example. Check Camtasia’s features at www.techsmith.com/camtasia/enhance.asp for specifics.

From Don W - What is the output format for... Captivate? – There are seven options. I’d say the most common is SWF for the movie, then Print (Word) for producing review copies or handouts. You can also output to Adobe Connect Pro, AVI, EXE, an email attachment with several specific formats, FTP, or a new (in Captivate 4) AIR-based “review” format as a way to move reviews off paper.

From Erin H - can you talk a little bit about how it integrates with other help systems? What things should we be aware of? I woudl like to include movies in online Help (and we use a content management tool for Help). Also, what can be done to minimize file size? – In Flare and RoboHelp, and probably any other tool that lets you insert SWF files, it’s a simple matter to insert a movie into a topic. The problem is that the movie runs automatically every time the user opens that topic, cool at first but wearing thin fast. A better solution is to create a separate topic to hold the movie, then add some link text in the main topic, like “Click here to see a demo” and popup link that text to the help topic that contains the movie. This lets the user decide whether to run the movie. Two points re minimizing the movie files sizes… First, reduce the number of graphics that you insert in the movie. Second, if you’re doing audio narration, do it in one or two takes rather than twenty or thirty to get the audio "just right", since all those takes add up.

From Cynthia K - how many tiers can you branch out to? – As far as I know, there is no technical limit. The only limit may be how many you can keep track of.

From Peter I - can you suggest approach for maintaining captivate movies? For ex., if one screen changes. – I think it depends on the size and nature of the change and its proportion to the overall movie. Overall, there are two main options. Re-shoot the changed material as a new movie, then import its frames into the existing movie and delete the original, now-changed, frames. Or, delete the old slides in the movie and use Cap’s re-record feature ( Insert > Recording Slide). I lean toward the first option because I find it less confusing, but that’s me.

From Susan H - Can we change text to variables after the fact? – You can remove text and replace it with a variable, if that’s what you mean…

From Linda K - may we use the music shipped with Captivate in our movies? are they copyright concerns? – As far as I know, the audio clips that ship with Captivate are freely distributable with no copyright issues, but don’t take my word for this. I'd contact Adobe to check, or else have your legal department do so.

From Susan H - Please confirm that Captivate DOES support double-byte characters. – Per the features page at www.adobe.com/products/captivate/features/, under the Unicode Support heading, it says “Create your content in any language, including double-byte languages, and count on Adobe Captivate to publish it properly thanks to Unicode text encoding”

From Linda K - How to change the default text used in the automatic captions? – Open the appropriate CaptureTextTemplates_.rdl language file in the Program Files\Adobe\Adobe Captivate 4 folder and change the default text as needed. This file is a bit programmatic, so make sure you’re changing the right wording. Back up the original RDL file before changing it.

From Erin H - perhaps you could post a short demo of using Captivate on your blog? – I’m going to run a brief (35 minutes) demo on Wednesday. Let me know if you’re interested in sitting in and I’ll send you the connection info.

More to come...

2009-07-27T10:28:00.000-07:00

About That Issue of Tech Writers and Business

I've heard from two people, so far, who read something other than what I intended into what I wrote about tech writers and business, so...

I don't assume that tech writers are incompetent or incapable of understanding business issues. Nor do I hold tech writers who come from fine arts or English backgrounds in disdain. (I have a bachelors in English myself.)

I simply believe that too many tech writers just don't want to get involved in the finance side of business, an attitude that holds those writers back from having a more influential role in their companies' operations. If tech writers are going to compete with consultants and outsourcing and offshoring firms, we need to be able to hold our own in business terms during operational discussions. That's it...

2009-07-27T03:57:00.000-07:00

Why Tech Writers Need To Understand Business - Yet Another Example...

For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them.

One area in which this problem manifests itself is finance. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions. Consider the decision to buy a $100K+ CMS. Spending that much money may require formal cost-justification. If the doc group can't provide it, then either the CMS won't get bought or will get bought but under the control of another department that may or may not take the doc group's needs into consideration.

But there are other areas in which ignorance of business can hurt. One, security, was the subject of an article in a recent issue of Business Week (July 27, 2009, "Google's Battle for the Office"). Here's a quick backgrounder...

Google appears to be attacking Microsoft by undercutting Windows and Office. Google's Chrome browser will let users run applications, like word processors, that reside on a server rather than on users' desktops. And Google's application suite, Google Apps, is intended to compete with Office but with the applications also on a server rather than users' desktops. Undercutting Windows and Office would reduce Microsoft's revenue stream and thus weaken Microsoft.

Love or hate Microsoft, there is some benefit to Google's approach and Google is pushing it. The problem, as the Business Week article noted, is security. Google Apps stores files, like word processing documents and spreadsheets, on Google servers rather than on the client companies' own servers. This means the client companies give up control of their proprietary material. Quote Business Week - " For some companies, the arrangement violates security and accounting policies."

Business trumps technology...

2009-07-13T06:50:00.000-07:00

Questions from the July 7-10 Remote Flare 5.2 Course

Re looking for the definition of "inline marker" as an impromptu test of the help's usability... I found it in under a minute by opening the help Search pane, searching for "inline", clicking "inline markers" in the auto-complete panel, opening the first topic - "Frame Contents Window Pane," and scrolling down until I found the two words highlighted. Here's the definition, from the v. 5.2 help...

"...markers for all inline elements in the active topic. You might find this feature useful if you have imported DITA file content. The reason for this is that DITA inline tags are often for semantic purposes, rather than for changing the look of content. By enabling the inline markers feature, it is easy to tell when particular content is using a tag."

The problem here is the need to scroll almost halfway down the topic to find the definition. However, the highlighting helps. So I'd call this pretty usable...

2008-12-15T02:11:00.000-08:00

Can You Use a Help Authoring Tool As A Content Management System?

An upcoming vendor-neutral webinar presented through MadCap Software...

If your documentation group is considering adopting a CMS, you may find that training, workflow, and cultural hurdles can make implementation harder than you think. And even a simple commercial CMS is far more expensive than traditional authoring tools, so those hurdles can get expensive.

Help authoring tools (HATs) like Flare and RoboHelp seem unrelated to CMSs, but HATs have gone far beyond their help authoring roots. They offer, or are starting to offer, features like repositories, version control, review management, content customization using conditionality and variables, and more. HATs today are effectively lightweight CMSs.

This means that if you're planning to move to a CMS, you may be able to use your current HAT to create a simulated CMS to find operational problems before buying the "real" CMS. You may even find that you can use your HAT as your CMS, saving a lot of money and upheaval. That's the subject of this webinar.

This webinar will take place on Thursday, March 12, from 9 AM to 10 AM PT. For information or to register, go to www1.gotomeeting.com/register/187845873. For information about other MadCap webinars, go to www.madcapsoftware.com/training/webinars.aspx

2008-11-08T04:02:00.000-08:00

AIR and Tech Comm

For those people who got tripped up by the webinar ID change on Thursday, November 6, here’s the AIR overview that we covered.

AIR (Adobe Integrated Runtime) is a fairly new output type from Adobe that’s a hybrid of a browser-based application and a desktop application. Adobe is implementing AIR across its product lines, and AIR is showing up outside Adobe as well, in the new release of MadCap Flare for example. Here, I’ll discuss AIR from one perspective – online help and documentation created using RoboHelp (and other tools like Flare).

First, a little history to put AIR in context…

In the late 1980s, Microsoft released Windows Help (“WinHelp”), the first mainstream online help format. One of WinHelp’s attributes was that it was “compiled”, combining all the topics in your online help or documentation into one file, the HLP, for distribution. (There was one more file, the CNT, but we can ignore that here.) Whether you had 1 topic or 1,000 in your help, they were distributed as one HLP file. This one-file model made WinHelp easy to distribute.

In 1997, Microsoft released WinHelp’s successor, HTML Help. It too was compiled into and distributed as one file (no CNT this time), the CHM. As with WinHelp, the one-file model made HTML Help easy to distribute. But this time, the model got tripped up by the spread of networks in general and the web in particular.

HTML Help wasn’t designed for a web-based world or non-Microsoft world. This meant it could only run on Windows PCs with IE, and could only run locally or from a network drive. As people began turning toward the web, and as other formats like Linux began to take off, HTML Help began hitting its limits. This happened pretty quickly; as early as mid-1997 people were complaining about how Microsoft-centric HTML Help was.

In late 1997 or early 1998, eHelp came out with a solution – WebHelp. WebHelp looked similar to HTML Help but didn’t bundle the topics into one distributable file. Instead, WebHelp kept topics as individual files that were managed by various control files. In effect, WebHelp was a web site with a documentation-like interface. This added great flexibility. WebHelp could run on almost any platform and browser and from any location (local, network drive, or server).

But it had some problems. Because it was not compiled, a WebHelp output had as many files as there were topics, graphics, and control files. A 1000-topic WebHelp system might have 1500 files, which made engineering and network management very unhappy. (“Fifteen-hundred files! For a help system!?”) Plus WebHelp places a heavy testing load on vendors since it has to be tested under and reconciled for different browsers and new versions of existing browsers.

So the ideal solution would be an output format that could run locally in order to reduce network traffic, that went back to the one-file model of WinHelp and HTML Help, that got away from the browser compatibility problem, and that was network aware… AIR.

When you convert an online help or documentation project to AIR, the AIR “packager” bundles the topics, graphics, and control files into one file with an AIR extension that runs locally. It avoids the browser compatibility problem by using its own viewer. It’s network-aware to handle updates. It has WebHelp-style attributes like the ability to use skins to customize the interface. It lets you create links to external targets like web pages and can run them in separate windows. Plus, because it’s running locally, it can take advantage of local features like file writes. For example…

The screen below shows a simple WebHelp project created in RoboHelp HTML 7. It has the usual tri-pane features, some formatting, and a link (“Show me how”) to a SWF movie created using Captivate.

The next screen shows the same WebHelp converted to AIR. It keeps the tri-pane look and the link. The formatting got lost on conversion but can be recreated. This output also adds the “Resources” link at the top right which offers a drop-down list of external links. Note also that there are two pages open – Base Conversion and Hyper/Word Services – each in its own tab.

So the output would call for some minor tweaking (which should decline in later releases of AIR), but all in all, a good thing…

On the minus side, several things to consider:

AIR requires that developers (not viewers) have the JRE (Java RunTime Environment) on their PCs. This isn’t a big deal, but Sun’s download page can be a bit confusing.

AIR’s use of a proprietary viewer instead of a browser isn’t a big deal unless you support “zero-footprint” environments where viewers can’t download anything to their PCs. That means they won’t be able to download the viewer and thus can’t view the AIR file. This is a problem now but history suggests that it may lessen. For example, in 1997, WebHelp developers couldn’t be sure that viewers had any browser; today, it’s taken for granted. In 1999, developers couldn’t be sure that viewers would have the Flash Player; today, according to Adobe, 99% of all web-capable PCs have it. The AIR viewer is the latest in the “we’re not sure if users have it…” category but, if AIR takes off, the viewer may turn into one more default feature on users’ PCs.

AIR’s ability to use local PC features can be a security risk. Adobe is attempting to deal with this by requiring that developers create digital certificates for their AIR applications.

To sum up, I don’t know what the AIR’s future is but Adobe is making a big push for it and it’s definitely worth a look. For more information, go to www.adobe.com/ and search for AIR. To download the RoboHelp Packager for AIR, go to www.adobe.com/products/robohelp/robohelp-packager-for-air/

2008-11-07T07:47:00.000-08:00

Answer to Mimic Question from DocTrain East Workshop on Nov. 1

Let's say that you create a text caption box in a Mimic movie frame, add some text that includes a variable, and size the text caption box so that its borders fit tightly around the text. Furthermore, let's say that the value of the variable is "ABC".

If you then change the value of the variable to a longer entry, such as "MadCap Software, Inc.", might some text be pushed outside the borders of the text caption box? Yes.

If so, how do I fix this to be sure that all the text fits inside the borders of the box? You have to adjust the size of each text caption box by hand. A better solution is to size each text caption box whose text contains that variable so that all the text will appear inside the box when the variable's value is set to the longest possible entry - e.g. "MadCap Software, Inc." This way, you know that all the text will appear in the box when you use shorter variable values. There will be some excess white space in the box, but you won't run the risk of having to modify the size of the box every time you change the value of the variable.

2008-10-13T02:05:00.000-07:00

Chrome - the Google vs. Microsoft War Heats Up...

After a three-month hiatus, the blog is back...

In February, I wrote a column called "The $44.6 Billion Paradigm Shift" for STC's Intercom magazine. The column looked at Microsoft's aborted attempt to buy Yahoo and what that meant strategically. The gist of the column was that Microsoft saw a long-term threat from Google as the latter works to shift applications from the desktop to the web. Such a shift would make Microsoft's domination of the desktop irrelevant and cause a disastrous cut in Microsoft's revenue stream. (If you don't need the desktop, you don't need Windows...)

The latest sally in this war comes from Google with its release of Chrome in early September. On the surface, Chrome is just a browser. But it also offer an environment in which to run applications like Google Docs, without going through Windows. It has a ways to go today; we're looking at v.1 or, more accurately, a beta v.1 that really uses the Chrome interface to launch the application, which then opens in your regular browser. But the idea is likely to be refined in later releases, just as Microsoft went through several early releases of Windows before getting it (largely) right. If you remember the infamous Microsoft Bob, you get the idea.

I'll discuss Chrome in more detail in my Bleeding Edge column for STC's Intercom. If you're not an STC member but would like a copy of the column, email me at the beginning of November.

One side note about Chrome - how does it work with the output from popular help authoring tools. In a totally unscientific test, I tried viewing two different WebHelp projects through Chrome, one created in RoboHelp 7, the other in Flare 3.1 and then imported into Flare 4. The results?

Everything seemed to work in the Flare project - graphics, links, formatting, and navigation tabs (TOC, Index, etc.)

Almost everything seemed to work in the RoboHelp project. The graphics, links, and formatting all worked, which makes sense since they're basically standard HTML. But I ran into two problems. First, when I opened a topic containing a Captivate movie, the movie display box appeared but a message indicated that I needed to download the Flash player. I did and the movie ran fine, but I'm not sure why I had to download the player since it was already on the machine. More serious was the fact that the navigation tabs displayed but the TOC and Index tabs were empty. More research on the horizon...

2008-07-28T10:02:00.000-07:00

Remaining Questions From Remote Flare Course

Sorry about the delay, folks. Here are the answers to the remaining questions…

How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.

Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.

Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.

2008-07-22T13:47:00.001-07:00

First Issue From the 7/21-7/22 Advanced Flare Course

Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.

More to come over the next few days.

2008-07-20T07:43:00.000-07:00

A Word and Framemaker File Import Peculiarity in MadCap Flare

If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.

The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.

The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.

The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?

The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.

So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.

2008-07-11T12:34:00.000-07:00

Why Migrating From Word To An XML-Based Document Authoring Tool Won’t Be Easy …

Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…

XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.

1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…

2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.

3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.

4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.

The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)

To create a new document in xMetal, you select File > New.

The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.

The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.

The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.

2008-06-21T03:24:00.000-07:00

Follow-Up to Yesterday's Post About AIR

If you read yesterday's post when it went up, be sure to go back and look at the comments section. Two very useful comments from consultant Peter Grainge and AIR Product Manager Rob Christensen.

2008-06-20T05:22:00.000-07:00

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.

2008-05-21T04:11:00.000-07:00

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.

2008-05-03T04:46:00.001-07:00

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.

2008-04-28T11:58:00.000-07:00

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.

2008-04-20T05:29:00.000-07:00

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.

2008-03-26T04:08:00.000-07:00

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.

2008-03-10T13:08:00.001-07:00

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...

2008-02-29T01:35:00.000-08:00

MadCap Analyzer

My apologies for commiting the cardinal blogging sin of not posting, but four major projects hit me simultaneously in October and something had to give. Three of those projects are now history and the fourth is almost done, so I can start blogging again...

MadCap Flare is a powerful and feature-packed product, but it's long been deficient in the area of project reporting - the ability to report on such things as the styles used in the project, topics that have not been listed in the index, and so on.

MadCap recently corrected this deficiency with its release of Analyzer. Analyzer is a surprisingly powerful utility that can parse a project and then create reports listing the results, and even suggest improvements to the project.

Analyzer analyzes your project (sorry...) and provides a summary of various issues like the number of topics that have not been added to the table of contents or index, the number of styles in the CSS that have not yet been used (suggesting that they might not be needed in the CSS at all), and so on. Double-clicking an entry in this summary opens a separate window that presents more details about that issue and lets you correct the issue in Analyzer or in Flare (or the forthcoming Blaze).

Analyzer provides a lot of useful information about a project and can be considered the Flare (and Blaze) equivalent of RoboHelp's Reports feature (on the RoboHelp Tools menu). More specifically, Analyzer lets you look at TofC and index entries, variables, snippets, styles, and more. It also flags developer errors, such as undefined styles, variables, glossary entries, and other features that are easy to accidentally leave unfinished. A nice touch is the Replace Local Style Suggestions feature, which flags places in the project where you used local formatting and suggests replacements from the CSS.

Like any other v.1 software, Analyzer has some problems. I ran it on a mid-sized (~700 topic) Flare project and found one apparent problem and one surprising omission:

The problem is the length of time Analyzer took to do the initial analysis of the Flare project, which it has to do before any other Analyzer functions can kick in. It took about five minutes to analyze my topic project. Without any baseline, I can't say whether this is slow, fast, or normal, but it seemed slow.

The omission is the inability to create a simple list of topics in the project. This is a very useful feature, at which RoboHelp excels, because it makes it easy to create project task checklists. For example, let's say you imported an old WinHelp project into Flare and need to look for and fix the style class on the popups. How do you keep track of which topics you've checked? You can just open Flare's File List, which lists the topics alphabetically, and work your way down the list, as long as you don't need to make marginal notes about some topics. A printed, alphabetic list of the topics is a lot more useful. Surprisingly, there's no way to do that in Analyzer *through the interface* or in Flare itself.

There is one way around this omission. It's not perfect, but it's better than nothing. Thanks to Ryan in tech support for suggesting this trick...

One of the reports that Analyzer offers is "Topics Not In Any TOC." So the trick is to temporarily remove all TOCs from the project, which means that, technically, none of the topics are in a TOC and will thus appear on this report. You then generate and print the report, then put the TOCs back into the project. To do this:

1. In Windows Explorer, open the ...Project/TOCs folder under the project folder and change the name of each TOC from .fltoc to .oldfltoc or something like that. The name change makes Flare "lose" the TOCs, which thus means that none of the topics are in a TOC. (Open the TOCs folder on the Project Organizer tab and you'll see that all your TOCs are gone.)

2. Go to Analyzer and run the Topics Not In Any TOC report.

3. Change the names of the TOCs back to the original fltoc extension.

4. Close the project in Flare, then re-open it, to restore the listing of your TOCs in the TOCs folder on the Project Organizer tab.

The flaw in this trick is that it is a work-around that requires you to go behind the interface in Flare. But it does work. The drawback is the fact that this trick can't generate an alphabetic list of all the topics in the project. Instead, it generates an alphabetic list of all the topics as they're listed in each folder and sub-folder on the Content Explorer tab in Flare. This means that you can't just scan down the list to find a topic, but instead have to know what folder to look in in the first place. It's not that difficult if you know your project, but it is inefficient.

In summary, Analyzer is fairly inexpensive - regularly $299 but currently available at the promotional price of $199, at a discount for Flare maintenance customers, and free for MadPak maintenance customers. It offers a level of project analysis and reporting that's been sorely missing in Flare, and I recommend it highly.

2007-10-30T09:02:00.000-07:00

An "Interesting" WinHelp Development

On July 1, I wrote an entry describing what WinHelp is and discussing its drawbacks, such as:

- Possible security risks from its use of macros.

- Its lack of "web-ness".

- The declining number of authoring tools that support it.

- The declining number of authors that know how to use those tools.

- The declining number of authors who know the codes in case something goes wrong in the tools.

For those companies that still do WinHelp, the projects are becoming increasingly unstable. In my experience, most WinHelp authors today follow instructions written by long-gone predecessors but don't know what's happening under the hood.

Fortunately, there's always the authoring tool vendor's tech support. It's inefficient, since the support rep rarely knows WinHelp and has to research the answer in the company's knowledge base, but you'll get an answer. Until last week...

I'm converting an old WinHelp project created using RoboHelp Classic (now RoboHelp for Word) to Flare WebHelp. Parts of the project date back to the mid-1990s so, not surprisingly, a file was corrupted. After spending an hour in the code, I called Adobe tech support to see what they had in the knowledge base. After some discussion, the support rep told me that he had found nothing!

It's risky to read too much into one episode. It might have just been sheer bad luck on the support rep's part. But it was also clear that he knew nothing about WinHelp. Why does this matter?

It matters because it means that the help-of-last-resort for WinHelp authors just got wobbly. If your tool vendor can't help, it means that any conversion from WinHelp to HTML must go flawlessly via the authoring tool because, if anything goes wrong and you can't find a consultant who knows WinHelp, you'll be stuck. To me, this is a glaring signal that it's time to start leaving WinHelp now.

2007-10-08T17:47:00.000-07:00

Snippets and Variables

The content that technical communicators write often varies or repeats. For example, you might write a help system for a product called Longhorn and refer to the product by name throughout the help, only to have to change the name to Vista for release. Or you might write a Note in one topic and re-use it in twenty other topics, only to learn that you have to change the note’s wording everywhere for release.

There’s a familiar solution for these problems - search and replace. For example, search for the word “Longhorn” and replace it with “Vista”, or find and replace each instance of the note. But this solution isn’t perfect. You might miss an instance of the old term if you mis-spell it or use the wrong case. Or you might have to replace the note with a new version in multiple topics, so you have to copy the new note text, search for the old note, find and select it, and paste the new version over it. This is simple, but calls for a lot of concentration. Variables and snippets, offered by most mainstream authoring tools, are a better solution.

A snippet is a more powerful form of variable, so I’ll start by defining a variable.

A variable is just a placeholder with a name and a value, such as a variable with the name ProdName and a value of Longhorn. If you insert this variable wherever you’d normally have typed the product name, Longhorn, you’ll see the variable name but the reader sees the value – Longhorn. And when the product’s name changes to Vista, you just change the variable’s value to Vista in a variable control file. That change instantly applies to the entire project, “Longhorn” changes to “Vista,” as long as you inserted it as a variable rather than typing it. This offers two major benefits:

You can easily change a piece of information, like a product name or client name, across an entire project. You can also easily eliminate mis-spellings of repeated terms. If a term is mis-spelled once, it will be wrong everywhere because the variable value was mis-spelled. This makes it easy to fix; just change the spelling for the variable’s value.

Variables have one shortcoming. They only show text; no format or style. This is rarely a problem because variables are typically inserted within a paragraph of text, so they use the paragraph style. Most problematic may be the inability to contain links, graphics, or other attributes besides text, in a variable. The solution is the snippet.

A snippet is similar to a variable but more flexible. It can include links, graphics, styles, even variables. This means snippets eliminate the shortcoming of variables, have the same benefits, and add greater flexibility. That flexibility may be enough to let snippets and variables together to act like a simple CMS (Content Management System). How?

Because help topics can call snippets, you can create topics that are nothing but skeletons that call snippets. Each call to a snippet could be turned on and off using conditionality. You could also conditionalize the content of the snippets themselves. You can also insert variables in your snippets and control their values. The result is a collection of modules whose content and display can be finely controlled by using standard, simple features in your authoring tool. The real problem is managing and documenting what you did for the benefit of the next developer.

In summary, if you have to deal with content that varies, or that may vary and be inserted in many places in a project, or need to create modular content but not enough to justify the power, complexity, and cost of a CMS, look closely at the variable and snippet features in your help authoring tool.

2007-09-17T02:09:00.000-07:00

Templates for Online Help Projects

When creating online help, many authors just create the project and immediately start writing topics. However, help projects have various support files in addition to topics – templates, skins, style sheets, etc. – and it’s more efficient to create them before starting the actual project. Once you do, you can re-use these files in other projects in order to get a lot of consistency from project to project with very little effort. In this post, I’ll discuss one of these support files, the template.

A template is a master document that contains items to be re-used in multiple topics, such as the headings in a topic or even the wording of some content. For example, if multiple authors create task description topics, each topic’s content will obviously differ but the order in which that content is presented should be the same for each topic – the title, a “Required Materials” section, an “Applicable Date” section, and so on, for example. This seems straightforward; why not just have the authors agree on a design, without bothering with templates?

Ideally, all the authors will write the same types of topics consistently – same headings in the same order, same wording for similar “Notes,” and so on. In reality, each author will soon diverge from any one consistent standard. This inconsistency forces authors to think about the structure, sequence, and wording of each topic, so the writing gets harder. The inconsistency also forces readers to verify their mental model of how the material is presented each time they read a new topic, so reading and comprehension are harder.

Templates can ease this problem. If authors need to create a particular type of topic, they create it not from scratch but instead based on a pre-defined template for the topic type. This provides the structure for the topics automatically. Authors can also attach a style sheet to a template so that any topic created using the template not only has consistent structure but consistent styles as well, also automatically. The result is more consistent content that’s faster and easier for authors to write, easier for readers to read and comprehend, and constitutes the first steps toward structured authoring.

Attributes of Good Templates

Limited to your main information types. Analyze the types of topics you create. You’ll find that a few types make up most of the topics. For example, you may find that concept, task, and reference topics make up 95% of what you write. This means that you only have to create a very small number of templates.

Simple to use and the more intuitive the better. If it’s hard to use, or requires training or instructions, fewer people will use it. Remember that any template is competing with your authoring tool’s File > New option, which is about as simple as you can get.

Self-documenting. Template developers often write instructions explaining how to use a template but the template won’t be used if those instructions get lost. A better approach is to make the instructions part of the template itself. For example, the marker for a topic title might be something like [delete this text and replace it with the title]. For example, in a sample “task” template:

[delete this text and type the title]
[delete this text and type the intro description]
Date of Applicability
[delete this text and type the date]
Required Materials
[delete this text and type the first entry in the materials list]
[delete this text and type the next entry in the materials list]
and so on…

“Sold” as being a benefit to the authors, especially if the authors are low-tech or third-party authors rather than a part of the doc group.

Creating and Using Templates

Templates are easy to create and use. Follow these instructions for three common tools:

In RoboHelp 6
(These instructions may change in RoboHelp 7).

To create:
1. Right-click the Templates folder on the Project tab and select New Topic Template.
2. Name the template, click the Appearance tab to link a style sheet (presumably created earlier) to it, and save it as .htt in project folder.

To use:
1. Click the New Topic icon and select the template from the Template pulldown on General tab.

In Flare 3.X

To create:
1. Create the topic that you want to use as the template and apply a style sheet to it.
2. In Windows Explorer, create a My Templates folder under the My Documents folder.
3. Create a Content folder under the My Templates folder.
4. Save the topic to be used as the template in the Content folder.

To use:
1. Click the New Topic icon, select My Templates in Template Folders list, and select the desired template.

In Word 2003

To create:
1. Create a new document to be used as the template and apply styles.
2. Save the document as .dot in the Templates folder.

To use:
1. Select File/New, select On My Computer under Templates in New Document pane, and select the desired template.

Easy…

2007-08-11T04:13:00.000-07:00

What’s Up with RoboHelp?

RoboHelp has had some rough times in the last few years. By early 2006, many people, myself included, assumed it was dead and were surprised when Adobe announced otherwise and then released version 6.

When RoboHelp 6 appeared, it met with near-explosive disdain in many quarters because the changes seemed so minor compared to people’s expectations and hopes. I got many questions about it because my involvement with the tool is well-known, and my answer was that I thought 6 was more of a public relations release than a “real” release – Adobe’s way of saying that RoboHelp wasn’t dead and that authors should hang on a bit longer. If I was right, RoboHelp 7 would be the test. Would Adobe have used the breathing room provided by version 6 to make significant changes to 7?

RoboHelp 7 isn’t out yet, but Adobe gave several sneak peeks at the STC annual conference in May. Based on those sneak peeks, I think my assessment was right. The changes promised for version 7 represent a major upgrade. Here are what I view as the high points from the sneak peeks:

No more kadovs – Kadov long ago became legendary as a sign of RoboHelp’s lack of code cleanliness. In fact, its importance depended more on what you were creating. If you were creating projects that would have to be converted or processed somehow, or were dealing with very standards-driven IT groups, the kadovs were a problem. However, if you were creating projects as end products with no post-processing or conversion in mind, the kadovs were a minor issue. As long as the project displayed correctly, the kadovs were inelegant but not critical. Adobe appears to have gotten rid of the kadovs in RoboHelp 7, finally settling the issue. A strong improvement at the code level.

MDI (Multiple Document Interface) support – RoboHelp always displayed one topic at a time in WYSIWYG. If you wanted to compare two topics or cut and paste material between them, you had to open and re-open the two topics but couldn’t have them open together. The MDI support lets you do that. I’ve never thought MDI support was all that significant but many authors disagree with me, so we’ll call it a strong improvement at the authoring level.

Snippets – RoboHelp 6 added variables, making it a lot easier to tailor projects – to different clients, for example. However, variables are text-only and can’t be formatted. Snippets should let you create re-usable chunks of content that you can insert throughout a project and update like variables, but also format. A nice touch will be the ability to insert variables into snippets. A strong improvement at the authoring level.

Unicode and double-byte support – This will make it easier to create outputs for non-Romance languages like Hebrew or Cyrillic and Asian languages in general. A strong improvement at the authoring level if you need to translate or localize, largely academic otherwise.

Vista/Office ‘07 support – I think Vista and Office ‘07 will spread into the office world slowly since their processor and memory needs will often require buying new hardware. Many older PCs just won’t have the horsepower to be upgraded to Vista. However, the lack of support for Vista and Office ‘07 in RoboHelp 6 had to be a bit embarrassing for Adobe. An improvement at the technical level.

Multiple ToC support – This will let you create complex single source outputs without having to swap multiple ToC files in and out of projects through Windows Explorer. A strong improvement at the authoring level.

Interface customization – RoboHelp always supported limited customization of the interface by letting you show or hide the toolbars, and move toolbars around, but that was it. The sneak peek promises more toolbar customization features, plus function “pods” that can be moved around or hidden as needed. You can also save a specific configuration of toolbars and pods for recall, like the memory button in a car seat. An improvement at the authoring convenience level.

The sneak peek did not list several things, such as information about the version control system, support for Web 2.0 features, and my pet issue…

Native XML support – I don’t know if this means RoboHelp 7 will stay as HTML and use the minimal XML support from versions X5 and 6, or whether Adobe is working on XML support and simply didn’t list it in the sneak peek. Adobe and I have disagreed about the need for XML support in the past. If they’re not going to offer more XML support in RoboHelp 7, I have to assume that Adobe’s market research showed that it’s not that important to current authors in major clients. The question is how that might affect support for XML-based formats like DITA. Perhaps in RoboHelp 8…

In summary, assuming that the features discussed in the sneak peek show up in the release version of RoboHelp 7, I rate it a big improvement over version 6 and a further reassurance to current RoboHelp users that the tool is very much alive.

2007-07-21T05:53:00.000-07:00

Out of Control – The DIGG Riot and Web 2.0

Web 2.0 has a few basic principles. Two – social networking and user-supplied content – are familiar; they’re often written about and have real-world analogs. But there’s a third – disintermediation, eliminating the mediator or middle-man – that carries some big risks along with its benefits.

Disintermediation is good because it eliminates information bottlenecks, especially if the information is coming from many sources, like the members of a user community. Web sites like Digg (digg.com), provide a rating service based on the collected and aggregated opinions of a community of users. The lack of a mediator, at least an overt one, is a plus. Consider Digg’s description of itself:

“… a place for people to discover and share content from anywhere on the web. From the biggest online destinations to the most obscure blog, Digg surfaces the best stuff as voted on by our users. You won’t find editors at Digg — we’re here to provide a place where people can collectively determine the value of content…

How do we do this? Everything on Digg — from news to videos to images to Podcasts — is submitted by our community (that would be you). Once something is submitted, other people see it and Digg what they like best. If your submission rocks and receives enough Diggs, it is promoted to the front page for the millions of our visitors to see.”

It sounds good but there’s one flaw, the assumption that a community’s motives are good. What if they’re not? The result may be that your content gets taken captive and you may be unable to do much about it. Consider the “Digg riot”.

Overview of the Riot

In February, someone leaked the decryption key for HD-DVD and Blu-ray disks onto the internet. The key uses technology created by a consortium made up of Microsoft, IBM, Intel, and other heavy hitters.

Toward the end of April, the key was posted on Digg. The consortium filed a cease-and-desist order, and Digg began deleting posts containing the key and suspending posters. In response, users began flooding Digg with multiple messages containing the key, daring Digg to stop them.

Digg tried. At 1 PM on May 1, Digg CEO Jay Adelson wrote “…We’ve been notified by the owners of this intellectual property that they believe the posting of the encryption key infringes their… rights. In order to respect these rights and to comply with the law, we have removed postings of the key that have been brought to our attention… required by law to include policies against the infringement of intellectual property.”

The response was an avalanche of criticism. Posters to many forums (Google ‘digg riot’) called Adelson “fascist”, claimed that it’s impossible to copyright a key because it’s just a number, and so on. And Digg users continued to flood the site with copies of the key.

At 9 PM, Digg surrendered. Founder Kevin Rose said “We’ve always given site moderation… power to the community. Occasionally we step in to remove stories that violate our terms of use… So today was a difficult day for us. We had to decide whether to remove stories containing a single code based on a cease and desist declaration. We had to make a call, and in our desire to avoid a scenario where Digg would be interrupted or shut down, we decided to comply and remove the stories with the code.

But… you’ve made it clear. You’d rather see Digg go down fighting than bow down to a bigger company. We hear you, and effective immediately we won’t delete stories or comments containing the code and will deal with whatever the consequences might be... If we lose, then what the hell, at least we died trying.”

Dianne Lynch of Ithaca College summed up the situation in a May 7 ComputerWorld article. “If you’re going to turn the site over to the community, you can’t decide to change your mind without having serious implications. User-generated content means that users will make a collective decision about what is and isn’t appropriate.”

And Rod Carveth of Marywood University, said in the same article “Communities that develop on sites such as Digg… form their own social norms. And when they feel they are violated, they use their own sanctions, site administrators be damned.”

What It All Means

It’s risky to read too much into the story. There are big differences between Digg and the types of Web 2.0 applications that technical communicators are likely to create. But technical communication itself is evolving in ways that are hard to predict. The lesson here is to be aware of the risks of Web 2.0 before jumping blindly into the technology.

2007-07-01T05:13:00.000-07:00

Whither WinHelp (and WinHelp 2000)?

In the mid-‘80s, online help authors had a choice of many tools – Views, Window Book, Black Magic, etc. Each tool had an authoring module, costing about $500, and a user module, costing about $50 per user. The latter kept the market small because it was expensive to provide online help for each member of a large user community at $50 a pop.

Microsoft’s release of Windows Help, or WinHelp as it become known, in the late ‘80s changed this. It killed the older authoring tools, pushed hypertext into the mass market, and laid the foundation for online help as it exists today. WinHelp was unofficially terminated in ’97 when Microsoft released HTML Help. It’s now, apparently, been officially terminated with the release of Vista which, officially, no longer supports WinHelp. But dead or not, WinHelp is still used by many firms that, for various reasons, have not yet moved to HTML or XML.

So What is WinHelp?

WinHelp files are written in a format called RTF (Rich Text Format). (HTML Help uses, not surprisingly, HTML.) The RTF files are processed – “compiled” – into the finished output that’s distributed to users.

In the first version of WinHelp, the output was one file with an .hlp extension that contained all the topics and some minimal navigation features. Later versions of WinHelp added a second file with a .cnt extension that added table of contents, index, and search tabs. Users viewed the whole thing with a help mini-browser made up of one file – winhelp.exe, later winhlp32.exe – that came with Windows.

WinHelp’s authoring module was effectively free since authors could type the text and codes in Windows Notepad and use a free compiler from Microsoft to create the output. The user module was free since the winhelp.exe or winhlp32.exe file was bundled with Windows. The older hypertext systems couldn’t compete and either went out of business or went into niche markets.

Although authors could hand-code in Notepad, this was boring and a rich source of typos. Early authors created macros to speed up the work, and it wasn’t long before commercialized versions appeared – Doc-To-Help in ’91, RoboHelp and others soon after. The help authoring tool, or HAT, market was born.

Most early HATs were really Word plug-ins. They used Word’s features to create the content and add codes in regular .doc files, then converted the files to .rtf for compilation. In theory, authors could use any word processor to do this but Word was the easiest. As a result, authors who used other word processors, like Ami Pro, Manuscript, or WordPerfect for hard-copy but needed to create online help as well often migrated to Word, which hurt the other word processors’ sales.

WinHelp’s Output Structure

When users opened an early WinHelp file, they saw one window containing the help’s “home page”. Here’s an example, a WinHelp file that I wrote in the mid-90s as an introduction to graphics for new online authors.

Note that there’s no table of contents, index, or search tab. To see them, users clicked the appropriate button in the “button bar” below the menu. This opened a separate “navigation” window containing the table of contents, index, and search tabs. Separate navigation and content windows made sense early on, when no one knew the best way to design help, but soon proved inefficient because users had to actively reopen the navigation window in order to use it, a big drawback.

Another drawback was the fact that a typical WinHelp project might pack several hundred topics into one Word file. This caused two problems. First, a Word file containing the equivalent of several hundred pages of material might take twenty minutes to open. It was also difficult to manipulate individual topics.

Another drawback, though not obvious at the time, was WinHelp’s use of macros to control many of its features. Today’s security concerns didn’t exist in the early ‘90s but, for companies still using WinHelp today, the macros must be a concern.

Another drawback is the shrinking pool of authors who can create WinHelp. The tools that date from the early days of help, like Doc-To-Help and RoboHelp, were originally created for WinHelp and only moved to HTML later. So these tools still support WinHelp; RoboHelp for Word, for example, is the original RoboHelp of 1991, albeit much upgraded. But fewer and fewer authors know how these tools work or understand the details of WinHelp projects, like the +, $, and K and other symbols at the top of each topic. So companies that still use WinHelp are at risk of losing the ability to maintain their own help systems.

Finally, as technical communication continues moving into a web model, WinHelp can’t support the new features coming online. And it just looks old…

What About WinHelp 2000?

When Microsoft released HTML Help in ’97, it combined WinHelp’s separate content and navigation windows into one “tri-pane” window, as shown below.

To ease the shift to HTML, eHelp created a RoboHelp output that bridged HTML Help and WinHelp. It kept the WinHelp code but modified the look of the output to sort of resemble HTML Help. The result was WinHelp 2000, below. (The example is from RoboHelp for Word.)

It looks sort of like HTML Help in that it shows the content and navigation panes together – the “tri-pane” model. This is controlled by enabling a WinHelp 2000 feature and distributing a WinHelp 2000 plug-in with the .hlp and .cnt files. But it’s still WinHelp, and thus has all the disadvantages of WinHelp.

I’ll sum up by saying that WinHelp has a long and distinguished history and that it created much of today’s online help authoring world. But its end is in sight and it’s getting to be time to move on.

2007-06-10T05:50:00.000-07:00

HTML vs. XHTML

About the delay in this post… We spent two weeks on vacation in Alaska and a week cleaning up all the things that accumulated while we were gone. By way of atonement, here’s a photo of the Margery Glacier in Glacier Bay. It’s about 250’ high and periodically shed chunks of ice the size of phone booths to the tune of gigantic cracking sounds.

And now, back to computers…

If you evaluate different help authoring tools, you’ll see that many use HTML but some use a language called XHTML. In order to understand the difference between the two and why it matters, you need to understand some basic concepts of XML.

HTML (Hypertext Markup Language) dates back to 1990 and is the basis of the web. It’s still widely used but its limits began to appear as early as the mid-90s. To deal with those limits, the W3C (Worldwide Web Consortium – the main internet standard-setting body) introduced a new language called XML (Extensible Markup Language) around 1997.

Unlike HTML, which has about 90 codes, XML technically has none and isn’t a language at all. Instead, it’s a “meta-language,” a set of rules for creating custom codes/languages optimized for specific situations, as opposed to the general purpose but less efficient HTML. By way of analogy, if HTML is equivalent to the alphabet, XML is equivalent to a set of rules that let you create your own custom alphabets.

No one seems to know how many XML-based languages there are, but estimates are well over a thousand including CBL (Comic Book Markup Language), CSML (Cave Survey Markup Language), MAML (MicroArray Markup Language), another MAML (Microsoft Assistance Markup Language), and so on.

The ability to create your own custom languages obviously offers great flexibility but can cause problems. Someone must have defined the codes for the custom language that you want to use. That definition process is fraught with design difficulties (what codes do we need now and in the future?), technical difficulties (how do we implement those codes?), business difficulties (if two groups in the same company or two companies in the same industry create different sets of codes to do the same thing, whose codes get used?), and implementation difficulties (how do we get people to change the way they work in order to use XML?). I’ll discuss the partial solution – XHTML – a few paragraphs further on.

In addition to supporting custom languages, XML also requires adherence to code syntax rules. HTML has syntax rules but developers often ignore the rules in order to do things more efficiently, more creatively, or just differently for the sake of being different. Most such “hacks” still work, even though they violate syntax rules, because HTML browsers like Internet Explorer and Firefox are very forgiving. But this still causes problems; the browsers waste time figuring out how to deal with various hacks, HTML files from different developers may not work together cleanly, and so on.

So, given the difficulties involved in defining custom languages and the difficulties due to syntax violations in HTML, what’s needed is a language that addresses both problems, which brings us to XHTML.

XHTML (Extensible HTML) is basically HTML revised so as to follow the syntax rules of XML. In other words, it keeps the familiar HTML but enforces the syntax rules much more tightly. Developers can still break the rules, but far less so. Because of the need to follow the rules, XHTML is sometimes referred to as “HTML done right.” It’s so useful that the W3C officially replaced HTML with XHTML a few years ago, although HTML is still widely used.

I’ll summarize by addressing the obvious question – does it matter if you use HTML or XHTML? The answer depends on what you need to create.

If you want to create standard web sites or help systems, HTML is fine. There’s no need for XHTML. (But most authoring tools that create HTML today will probably switch to XHTML in the next few years so you’ll go from HTML to XHTML without even knowing it.) One of the best known help authoring tools, RoboHelp 6, is based on HTML but lets you import XHTML files into a project, converting them to HTML, or export HTML files out to XHTML.

If you want to create web sites or help systems that use newer XML-based standards like MathML (Mathematics Markup Language), SVG (Scalable Vector Graphics), or DITA (Darwin Information Typing Architecture), you’ll need to use XHTML instead because XHTML, by virtue of its following XML’s syntax rules, effectively is XML whereas HTML is not and thus can’t handle those new standards. One of the newest help authoring tools, Flare, uses native XHTML.

2007-05-18T04:31:00.000-07:00

RoboHelp for Word or RoboHelp HTML?

When you buy RoboHelp, you actually get two separate modules – RoboHelp for Word and RoboHelp HTML. Which one should you use?

It seems obvious – use RoboHelp for Word if you write content in Word, and RoboHelp HTML if you write content in HTML. Simple, logical, and wrong. It’s a common error, and a great example of unintended consequences, in this case because of a product name change. What’s the problem?

The original RoboHelp was an add-on to Word and just called RoboHelp. When eHelp, the original vendor, released the HTML version in the late ‘90s, it had to distinguish between the two versions so it renamed them RoboHelp Classic and RoboHelp HTML.

This fixed the problem for a while. However, as more and more authors went directly to RoboHelp HTML, without ever using Classic, the word “Classic” became confusing. New authors didn’t understand what it referred to. To fix this, eHelp renamed RoboHelp Classic RoboHelp for Word. Unfortunately, this new name only made sense to authors who knew RoboHelp’s history. Authors who didn’t know the history made the mistake that I described above. So which module should you use?

RoboHelp for Word was designed to create the Windows Help, or “WinHelp” format that dates from the late ‘80s. Microsoft unofficially terminated WinHelp when it introduced HTML Help in ’97, but WinHelp remains widely used. However, it is declining quickly because of its technical limitations in the HTML/XML era and because of development headaches in the Word-based environment.

So unless you’re still creating WinHelp (and it’s time to be migrating to an HTML-based format if you are), you should not be using RoboHelp for Word. Instead, you should be using RoboHelp HTML. Here are three major reasons why:

More up-to-date – After Microsoft introduced HTML Help in ’97, it largely let WinHelp stagnate in its technology and its interface. The result is an output format that can’t take advantage of modern features and looks just plain outdated in our web-oriented world, unlike the HTML formats.

More efficient authoring – Many of the annoyances in RoboHelp for Word vanish when you move to RoboHelp HTML. Table handling is far better, with no more of the “Table cell borders not supported” errors, because HTML does a better job with tables than does Word. Topics are individual files, rather than combined in one huge Word file, so topic handling is more flexible. (Be warned, however, that you will lose some features that you take for granted, such as the non-scrolling topic titles and the button bar.)

Easier project maintenance – As HTML-based outputs have come to dominate the field in recent years, fewer and fewer authors know RoboHelp for Word. This means you may have a difficult time finding contractors or new writers who can maintain a RoboHelp for Word project.

But what if your subject matter expects write in Word? How do you use those documents with RoboHelp HTML? Not a problem; RoboHelp HTML can easily import a Word documents, automatically converting it to HTML and, in many cases, automatically breaking the Word document into a multitude of separate topic files.

In summary, if you’re not using RoboHelp’s HTML module, it’s time to think about it.

Note – I won’t be blogging again until the first week in June. Please check back then.

2007-05-09T10:39:00.000-07:00

I’m preparing for the STC’s annual conference in Minneapolis next week (May 13-16), where I’ll be giving five presentations – a full presentation, a progression, two booth presentations on Flare for MadCap, and a Springboard.

The full presentation is called “It’s Not My Aunt’s Online Help Anymore”, a wonderful line that I borrowed from an attendee in a Flare course last fall. My focus is on changes in the technologies, methodologies, and business practices of online help, with specific suggestions on how to respond.

The progression is a comparison of the differences in features and design philosophies of Adobe Captivate and MadCap Mimic. (They both come out looking good. The choice depends largely on what kinds of movies you want to create.)

The booth presentations cover Flare’s Word import feature and its output customization features - e.g. how to create one help system but tailor it to multiple audiences.

The Springboard is a short (15 minute) discussion of why templates are good things for technical communicators and how to create and use them in Word, RoboHelp, and Flare.

If you’re going to attend the conference, I hope to see you in one of these sessions. If you won't be at the conference but are interested in any of the sessions, email me at nperlin@nperlin.cnc.net and I’ll send you the Powerpoint slides.

2007-05-05T04:18:00.000-07:00

Responding to the comments about my May 2 post, with apologies for deviating from the low-gibberish quotient that I promised…

Re Tom’s point about formats supported by the DITA Open Source Toolkit and why WebHelp isn’t one of them - Officially, I don’t know. Unofficially, I’m pretty sure this is why…

Any authoring tool provider has to offer not only the tool itself but useful outputs as well. Without that, the tool is simply producing raw material. Converting that material to an output that can be distributed to users requires further processing, and that makes the tool less useful. So the answer is simple; make sure the tool can convert the material that it outputs to formats that can be distributed to end-users.

Every tool outputs HTML Help, for two reasons.

First, HTML Help, despite its age, is a standard. (It’s become an uncertain one and, in my experience, is in decline as people move to WebHelp, but it is still a standard.)

Second is a business issue. Tool providers can easily offer HTML Help because the “compiler,” the tool that turns the files in a project into a finished CHM, is part of a Microsoft tool called HTML Help Workshop that, I assume, Microsoft makes easy to license. And the “viewer” that runs the CHM has been built into Windows for years, so the authoring tool providers don’t have to do anything to make the CHM viewable on users’ PCs.

So all the authoring tool provider has to do is bundle HTML Help Workshop with the tool and add a few toolbar and menu options on the tool interface to launch the compiler and view the finished CHM. Easy…

(The same situation largely holds true for the older Windows Help and JavaHelp as well, which is one reason many tools offer them as well. Ignoring the fact that there are still companies using those formats, of course…)

In contrast, there’s no standard authoring engine for WebHelp. The idea of web-enabled output is the same no matter what the tool, but each tool provider has to create its own “WebHelp”. That means programming and expense. (They don’t have to worry about how to display WebHelp, however, since that’s taken care of by the browser.)

So the tool providers are in a tough position because some of their main outputs, like HTML Help, are easy to add to the tool but are in decline. The outputs that are growing in popularity, like WebHelp, require a lot more work on the providers’ parts.

On a side note, you can use DITA in any authoring tool that can import XHTML. Simply convert the DITA to XHTML and import the XHTML files into the authoring tool. The drawback is that you lose the DITA-ishness of the original files.

Re the question about Eclipse Help – I’m not that familiar with Eclipse Help yet, but it’s on my list of topics for future blog entries. In the meantime, Sarah summed it up nicely in her comment. There’s a lot of information about Eclipse Help available on Google.

Re Sarah’s comment – See above, and thanks for the feedback. As far as BBQ is concerned, see my BBQ page and look up the BBQ Rib Ranch in Sanford, FL, where I ate at the end of April. A gem…

Re Michael’s comment – Excellent points, thanks. The one thing I’ll add, which you sort of said at the end (“no one promised us that everything would be easy”), is that the level of complexity in the approaches you describe will limit these approaches to a very small and advanced subset of help authors.

2007-05-02T07:16:00.000-07:00

HTML Help vs. WebHelp

A classic question when creating online help or documentation is what output format to use, HTML Help or WebHelp? It’s important to pick the most appropriate format for your project. Fortunately, modern authoring tools are flexible enough that you can change the format during a project if you picked the wrong format when you began.

HTML Help

HTML Help is a format from Microsoft, and the successor to the older Windows Help, or “WinHelp,” of the late ‘80s and early ‘90s. Microsoft created HTML Help around ‘95 and introduced in February, ‘97. This means that HTML Help effectively predates the web, and it shows.

HTML Help is “compiled” – all the files that make up a finished help project – the topics, graphics, and control files – are contained in one file with a CHM extension that gets distributed to the users. So if you have one topic, you get one CHM file. If you have one thousand topics, you get one CHM file…

HTML Help’s Technical Requirements

HTML Help has three requirements:

Platform - It only runs under Windows. It won’t run on a Mac, Linux, Unix, etc.

Browser - It only runs under Internet Explorer (IE). IE need not be the default browser, but it must be on the user’s PC.

Location - It can only run “locally,” on a drive on the user’s PC. It was not designed to run on a web server but, until recently, could run on a network drive. However, security patches to Windows and IE now largely prevent this.

Pros and Cons of HTML Help

On the pro side:

Standard interface - Although developers can customize the interface, the basic interface is always the same – a toolbar at the top of the screen, three navigation tabs (Contents, Index, and Search) at the lower left, and the main topic at the lower right. So once users learn how to use one CHM, they know how to use them all.

Distribution - Simple. Just send the CHM.

Security - The CHM is compiled, and thus “closed,” so users can’t alter the text.

On the con side:

Outdated - The CHM looks proprietary and dated compared to the webbish look that today’s users are accustomed to.

The future - HTML Help’s use of HTML puts its technical future in question as XML begins to dominate. Microsoft could fix this by upgrading HTML Help, but Microsoft has been trying to move past HTML Help for years. Microsoft tried to replace it in the early ‘00s with a format called Help 2.0, but Help 2.0 never took off. Vista, the new version of Windows, has its own XML-based help format and, as Vista begins penetrating the market, Microsoft seems likely to shift resources away from HTML Help.

Confusion - The name “HTML Help” can be confusing. Listeners may think you said “HTML help”, which is not the same as “HTML Help.” The latter is a formal format, but the former is simply any web site that offers help and is written in HTML. I saw one project that got derailed for ten months because of this confusion. Be certain that your listeners understand that you mean “HTML capital-H Help.”

WebHelp

WebHelp was originally created by eHelp, the original maker of RoboHelp, in early ‘98 in response to the limitations of HTML Help. Today, every help authoring tool has some version of WebHelp.

WebHelp is “uncompiled HTML” – all the files that make up a help project – the topics, graphics, and control files – remain as individual files within an output folder that gets distributed to the users. So unlike HTML Help, where you always have one distributable file, you’ll wind up with dozens, hundreds, or even thousands of files with WebHelp. In effect, WebHelp is just a web site oriented toward online help and documentation.

WebHelp’s Technical Requirements

WebHelp’s requirements are basically the opposite of HTML Help:

Platform - It runs on almost any modern platform – Windows, Mac, Linux, UNIX, etc.

Browser - It runs on almost any modern mainstream browser – IE, Firefox, etc.

Location - It can run locally, on a drive on the user’s PC, but also from a web server or network drive.

Pros and Cons of WebHelp

On the pro side:

Webbishness - WebHelp looks like, and in fact is, a web site. So users will find it easier to learn because it will look familiar.

Vendor-independent - WebHelp is not tied to one vendor, the way HTML Help is to Microsoft. There’s less risk of your help format suddenly becoming unsupported.

Flexibility - The almost unlimited platform support, browser support, and file location offers almost unlimited distribution flexibility.

On the con side:

Distribution - Simple because there’s only one folder to distribute, but that folder may contain hundreds or thousands of files, which will make your network people unhappy. However, the fact that each topic is a separate file means that users are downloading smaller files than they are with HTML Help, thus reducing the load on your network.

Security - Because WebHelp is uncompiled, and thus “open,” users could alter the text in a topic file. This may be a serious risk.

So which Format Should You Use?

You’ll want to take your own specific requirements into account but, in a nutshell, use:

WebHelp if you need the distribution flexibility and the webbish look.

HTML Help if you need a pre-Vista Microsoft-standard look or want to “lock” the help to prevent users from modifying the content.