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.
Tuesday, October 30, 2007
Monday, October 8, 2007
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.
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.
Monday, September 17, 2007
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…
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
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
To use:
1. Select File/New, select On My Computer under Templates in New Document pane, and select the desired template.
Easy…
Saturday, August 11, 2007
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.
Saturday, July 21, 2007
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.
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.
Sunday, July 1, 2007
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.
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.
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.
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.
Sunday, June 10, 2007
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.
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.
Friday, May 18, 2007
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.
Wednesday, May 9, 2007
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.
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.
Saturday, May 5, 2007
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.
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.
Wednesday, May 2, 2007
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.
Subscribe to:
Posts (Atom)