Use variable placeholders to produce documentation for various cultures

When producing a help file, a user manual or an eBook, it is not only important to provide translations based on the targeted audience, but also to use the proper terms based on the readers’ languages. Let’s take the “colour” term as an example: “color” is the preferred spelling in American English while “colour” is preferred in all other main varieties of English. As a technical writer, supporting multiple language variants can lead to complications and extra work to make sure that the whole documentation is error-free. Thankfully, the HelpNDoc help authoring tool makes this task trivial and fast thanks to variable placeholders and its powerful build system.

Using variable placeholders

Variable placeholders are stored in and managed from the project’s library. They can be re-used in any topic and their current value will be used to generate the final documentation.

Let’s first create a new variable placeholder in our project’s library. That’s very easy to do:

In HelpNDoc’s “Home” ribbon tab, in the “Library” group, click “Add item”
Click “Add variable”
Enter any item name, such as “Colour-Term”
Enter the item’s default value, such as “colour”

Video guide: How to add an item to the library. Click to watch it...

We can now insert that variable placeholder in any topic, as needed. There are many ways to do it:

Select the item in the library, and place the cursor where it should be inserted in the topic. From the “Home” ribbon tab, in the “Library” group, click “Insert in topic”
Place the cursor where it should be inserted in the topic, right click on the library item in the library panel, and click “Insert in topic”
The fastest way: While typing text in the topic editor, start typing an exclamation point “!” and hit the CTRL + SPACE keyboard shortcut, continue typing the “Colour-Term” variable name and hit enter when it is selected to insert it in the topic

Video guide: How to insert a library item into a topic. Click to watch it...

Generate multiple documentation variations

Once the documentation is written, HelpNDoc’s powerful build system can generate multiple formats and variations for various target audiences.

We can now produce the documentation files for the end users. HelpNDoc can produce multiple documentation formats, including CHM help files, responsive HTML web sites, Word and PDF documents, ePub and Kindle eBooks and Qt help files. It can also produce multiple variations of those documentation formats thanks to its powerful build system.

Let’s create two HTML builds for various English spellings and override our variable:

See the how to create a new documentation output to be published step by step guide to learn how to create a new build
Then access the build settings
Override the value of the “Colour-Term” variable
Generate the documentation

HelpNDoc will automatically create two variations of the documentation, one will use the proper term for the American English and the other one will target all other varieties of English.

Going further with the command line

Once the builds are defined and enabled, HelpNDoc will automatically generate them when requested. But it is not the only way to override variables.

An alternative to creating a build for each variation is to leverage HelpNDoc’s extensive command line support: the build command can be used with the -v argument to override a variable as follows. This is particularly useful in an automated build system and a testimony of HelpNDoc’s versatility:

hnd5.exe project.hnd build -v=“Colour-Term:color”

HelpNDoc includes many more features to simplify and speed-up the process of writing great help files, user manuals or eBooks. Download your free copy right now to get started!