Your thoughts on using 300 variables in a Help system

[Guest]

Hi,

I'm researching the feasibility of using a large number of variables in a Help system. While I've used variables in the past, it was always for "traditional" items like product name, company name, etc. And never more than 10 or 15!

Our customers have the ability to dramatically customize our software, including the ability to change approx. 300 terms to suit their needs. My company would like us to replace these same 300 terms with variables in the Help system so that the customized terms that a customer uses have the same name in the Help.

I'm interested in any thoughts/experience that you might have regarding such a task. My main concerns are:

1. The Help system is currently around 700k words. I'm afraid that even with 6 of us combing through the files that a noticable number of terms will be missed.

2. 300 terms is a conservative number; we'll almost certainly have to add more to accomodate capitalized versions, etc. With this many variables, it seems to me that actually writing new material will be an unpleasant hassle, as a writer will probably have to break his/her train of thought in nearly every sentence to either determine if a term is a variable, or simply add the variable to the text.

3. Given my fear listed in #2, it seems to me that writing new material "traditionally" and then changing the appropriate words to variables later might be a viable solution. Of course, with this method, we still incur the risk of "missing" terms, and it does nothing to speed up editing existing material.

In theory, I totally support the idea of using variables (wisely). However, I believe that trying to manage 300+ variables is going to dramatically hurt the quality of our documentation (from a readability standpoint), is fraught with risk for incurring errors, and offers my company very little ROI, as I can't see customizable Help on this scale as a factor in tipping more sales our way.

Again, any thoughts, opinions, or experience that you can offer is greatly appreciated.

Thanks,
Roger

[Peter Grainge]

Welcome to the forum.

I agree management is going to be a nightmare. For a start, you are going to need a separate layout for each version of the variables and the client will have to let you have the variables they require. If not you would give them the project, if you are happy with that, and they could do it, and have to do it again each time you update the help. You could probably cheat that by copying the rhvariables.apj file but not sure that alone would do it, not without testing. Also you would not be able to add new ones so I don't think that is a good way to go, but it is an option.

Another thing that would be an experiment is to create each variable once and then do a search for the term and replace each instance of it with the variable code. Problem is words like port (as in PC) and port (as in a dock). You would have to check each one. FAR from http://www.helpware.net would let you do that. I am not sure without testing though that RH would accept that approach. Lucky if it does.

I think you need to play around with a copy of your project. Don't even think about trying those ideas on the live version.

Even then, you make good points at the end but that is a commercial decision for you and your company.

[Captiv8r]

Hi Roger and welcome to our community

My fellow Adobe Community Expert Peter is far too modest. Take a look at the following on his site. It may just be what you need. Click Here.

Cheers... Rick

[CraigCC]

Peter where is your sense of adventure

Hi Roger,

Firstly Peter is absolutely right it is a commericial decision and not one to take lighly.

I've been doing something similar with a project that has a lot of conditional content for many clients. There is one standard source and many different shipped outputs. It is a procedural based help system that has to cater for many different companys carrying out similar work. However, they do many things differently and use different terminology (e.g. for job roles, departments etc).

We used a complex search and replace script and BKreplaceEM for varaibles.

It is hassle, but it really helps sell the system as the companys get their own tailored look and feel.

I'm going down the variables route for this particular project and yes there about 500 variables. It is going to be so much easier once things are set up using only the variables feature.

You'll need some strict procedures in place if the client specifies the replacements for the variable names. I provide an extracted spreadsheet with standard terms and a blank column for them to complete. I always control the project and will not them loose on the .apj file.

It does get difficult when there is a big updates as the clients need to be given another spreadsheet with any additional terms - but they are fine with this.

In my opinion it is about giving the customer what they want, but making sure that they are charged realistic price for the work including the extra work involved when we make standard updates. It is also important to keep control of the project. It will get very complicated if you let them mess with the source files.

I would also make sure that one resource is responsible for coordinating this area of the project and that they remain sober at all times .

Good luck and fire away if you have more questions.

You may also find this useful - a recently updated article on variables.
http://www.adobe.com/devnet/robohelp/articles/userdefinedvars.html

Kind Regards
Craig