Variables vs Snippets

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
John Johann
Posts: 305
Joined: Mon Aug 21, 2017 7:35 pm

Variables vs Snippets

Unread post by John Johann »

I'm considering making adjustments to a project and adding a large number of variables or snippets. A lot of the text a user sees on screen in the application (e.g. labels in input dialogs) is repeated in the help topics followed by an explanation, so no surprises there. The label text in the help project is currently 'just typed in' as the help was converted from another system.
In order to simplify things, I'd like to take the label text from the application and put it in a variable or snippet which is then inserted in the topic.

My intention would be to auto-generate the variables/snippets from the application in various languages. That would hopefully keep texts the same and save some effort as only the explanations would have to be translated. Translation is currently decentralised. Due to the nature of the application, I would probably have well over 20,000 variables/snippets to output and reload when the help is built.

So my questions are:
Does anyone use such an approach?
Which is better -- snippets or variables (Most contents would be relatively short)?
Anyone work with large numbers of variables/snippets?
Is it possible to link to a database or mullti-lingual XML file to import language-specific text?
Simon_Dismore
Posts: 205
Joined: Thu Jul 13, 2017 2:57 pm

Re: Variables vs Snippets

Unread post by Simon_Dismore »

John Johann wrote:Anyone work with large numbers of variables/snippets?
Is it possible to link to a database or mullti-lingual XML file to import language-specific text?
No, but it only took a few minutes to try the variables method. I used Excel to create a pair of import files in the form:

Code: Select all

My1stVariable=Field 1
My2ndVariable=Field 2
..
My20000thVariable=Field 20000
I then loaded them into the Get Me Started example, one set via Configuration > Common Properties > Text Variables and another via Publishing Task Manager > Custom variables. Then I added a topic that used four of the variables (the 1st, 20000th and a couple from the middle of the list).

Results:
  • H&M can import 2 x 20,000 variables successfully.
  • However, it may hang 'Not Responding' for a minute or two doing this, and when you move to/from Configuration > Common Properties > Text Variables etc.
  • Within a topic, H&M's insert variable dialog can cope with 20,000 entries.
  • But you won't want to use this dialog to insert the variable name, because scrolling around a list of 20k items is too fiddly. After trying it, I instead defined a placeholder variable that sorts to the top of the list. Mine was 'AA'; I could easily use the variables dialog to insert <%AA%> and then overtype the desired variable name in the editor. Of course, in my case the names were predictable, that might not work so well in the real world.
  • H&M correctly used the orginal and task variables for publishing, at least to WebHelp.
So it works and took less time to test than to write up here. Whether it's a good approach probably depends to some extent on how your topics are structured, your translation workflow and so on. You could end up doing a lot of work in H&M that might be better done during translation. For example, what if some of your dialog labels are repeated within the explanation text? That would require the translator to use the same translation as your variable, and match gender, singular/plural etc.
Simon_Dismore
Posts: 205
Joined: Thu Jul 13, 2017 2:57 pm

Re: Variables vs Snippets

Unread post by Simon_Dismore »

Simon_Dismore wrote: I used Excel to create a pair of import files
If you want to repeat the experiment, the expression I used, repeated for 20,000 rows, was effectively:

Code: Select all

="My"&TEXT(ROW(),"0")&"Variable=Field "&ROW()
The variable names are automatically converted to upper case on import.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Variables vs Snippets

Unread post by Tim Green »

Hi John,

Further to Simon's reply: I think when you reach this number of variables you have left the point at which this approach is practical behind you quite a while ago. It's far too much for a human mind to process and confusion and a high error rate are not just likely, but guaranteed. Instead, you need to be working with translators who use a good translation memory system like SDL Trados. Then you don't need to use variables at all. The terminology is managed by the terminology database in the translation memory and handled automatically for all languages, provided you are consistent in your original/master language.

With translation memory you just send the full updated copy of the project to the translator. The system then processes the XML files and automatically translates everything that hasn't changed. The human translator then works on the rest, but they still have the translation memory for all the terms that show up in the new and changed text, so you won't get varying translations of the same terms once they have been translated correctly once. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
John Johann
Posts: 305
Joined: Mon Aug 21, 2017 7:35 pm

Re: Variables vs Snippets

Unread post by John Johann »

Thank you both for your input, testing, and comments.
As noted in the original post, I'm interested in people's day-to-day experience before I put too much effort in. The scrolling issue is already something which is unpleasant when shifting things around in large TOCs. As for entering the variables by selecting from the list, I'd be aiming to autogenerate and insert as much as possible and/or work in the XML directly.
A translation memory system similar to SDL Trados is not currently part of the workflow for various reasons. The idea with variables or snippets was to simplify transfer of information already existing/translated in the application to the help.

I've found working with *small* numbers of variables and snippets quite useful and agree that large numbers may not be practical. But I don't always get to choose :-).
Post Reply