Terminology Methods

What's covered?

Different users of a help system often use different names for what is essentially the same thing. For example Customer / Client or Warehouse / Depot. This topic describes how a help system can be created so that different clients can use their own terminology.

Please note that RoboHelp 6 has introduced a built in method of creating variables which has many advantages over the methods described here. Using the built in method will be described in an article on Adobe's site and I will create a link to that when it has been published. If however you cannot upgrade, then please read on.

Terminology Method 1 has been on this site for some time now and describes one way of allowing customers to use their own terms. There are some issues with searching and printing using that method but it still has some advantages over a new method that has been devised and is described and demonstrated under Terminology Method 2.

Perhaps the simplest thing to do is to set out the key differences so that you can see which you think will suit you best.

Feature	Method 1	Method 2
Ease of set up for author	Author has find of each occurrence of each word that is to be changed and then insert javascript. It is then no longer possible to see in the WYSIWYG editor what the default term is.	Author inserts four references to javascript files in each topic. This is a one off job and can be done using a multi file find and replace operation. The topic is not affected in the WYSIWYG editor.
Ease of set up for the customer	The customer has to indicate the term they want to use against each variable defined. If a term has not been set up as a variable, it cannot be added.	The customer defines which words are to be found and the replacement term. With this method, bubble text is available so the customer can add a description or they could leave the original term and list alternatives in the bubble text.
Searching	Neither the original term nor its replacement will be found by a search.	The original term will be found by a search.
Printing Topics	Will print the topic with the customer's terms.	In Webhelp, it will print with the customer's terms. In compiled CHM help, it will print a single topic with the customer's terms. If the user selects the option to print all topics in the book, it will print the default terms but it will also show an error dialog.
Format Options	The term will appear in the format defined by the author.	The term can appear In the same format as the rest of the paragraph It can be formatted differently for each word but all instances of that word will be the same It can optionally also have bubble text.
Table of Content and Index	Will not pick up the customer terms except with some additional work for webhelp only.	Will not pick up the customer terms.
Browser Compatibility for webhelp	Tested in Internet Explorer 6 and Firefox. May work in earlier versions.	Tested in Internet Explorer 6 and Firefox. May work in earlier versions.

Which is best?

I cannot answer that. It depends on the resource available to set things up and which options you think will best suit your customer.

Method 2 is much easier for the author to set up. Insert four references to javascript files in each topic and that's it, job done. You don't even have to think what terms a customer might want to change.
On the downside, Method 2 will catch each instance of a word. It will not consider context. In the topic on Method 2, I have described a company that produces accounts software and the company name is Dodgy Accounts. The method does allow case sensitivity to be taken into consideration which could help in this example, but that's the only exception. Every instance of accounts in lowercase will be found and changed. Sometimes you might not want that but there are no exclusions. If you need to make sure context is taken into account, then Method 1 is your choice.

Perhaps look at it the way I do. With 12,000 topics in one of my projects, Method 1 would be a massive task to implement retrospectively, had it bern done from the outset it would not be such an issue but I have to address the present, not what might have been. Method 2 using multi file find and replace tools will take me an hour or so to implement. Now guess which one I am likely to go for in my situation. We need to educate the customers about using the method carefully but they know if we now implemented Method 1, they would be paying somewhere along the line whereas we can throw Method 2 in for free.

Do not read that as saying forget Method 1, far from it. It remains a very valid method. In a different scenario I would be using it because of the control over each instance of the word.

Date	Changes to this page
15 Feb 2007	Reference added to the built in method introduced in RoboHelp 6.
29 Jan 2005	New topic. Terminology Method 1 has been described on this site for some time. With the introduction of Method 2, this topic summarises the differences.