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.

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.

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.

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…

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.

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.

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.