Close

Update software doc automatically

While creating and maintaining documentation, technical writers are often confronted with a myriad of challenges. For example, it is not exactly evident to ensure consistency between a software application (which is frequently updated) and its accompanying documentation. Luckily, Flow has a couple of solutions; one of which is to reuse software strings in your technical documentation.

Docs often aren’t in line with the software

Suppose you have a software application accompanied with documentation, such as a user guide, an online help or an API reference guide. You obviously want the text in your documentation to be consistent with the text in your user interface (dialog boxes, menu commands, display messages…). And of course you want the same consistency in your translations too.

Although you may find consistency in the first version of the documentation, is this also the case in later versions as the software gets updated? Maybe not, if the text from the user interface has been manually copied into the documentation. Each update of the software may then mean you will have to scrutinize the complete documentation set to find and fix inconsistencies, in the (English) source language and in the translations.

Reuse software strings

Fortunately, there is a better way to deal with this challenge: reusing the text from your software applications, aka the “software strings”, with a dynamic link in your documentation. The process goes as follows:

  1. You export the text from your software application to a structured file format, for example XML, CSV or JSON – while making sure that each software string gets a unique ID-number
  2. We then transform that file to a DITA file, where the software strings become reusable components.
  3. The technical writers no longer type the software strings in their documentation, but they drag them from a repository of reusable components into their content, thus creating a dynamic link; the right software strings are retrieved from the repository through that unique ID number and then shown in the documentation.
  4. As the software gets updated, only steps 1 and 2 are performed: export the text from the user interface again and retransform the software strings file into a repository or warehouse of reusable components.

Apply changes automatically

The software strings will now automatically change in all accompanying documentation every time the software strings are adapted in the software application. The dynamic link ensures that every adjustment in the repository of reusable components is passed on to the documentation – with thanks to the abovementioned unique ID numbers (these stay the same throughout).

A dynamic link ensures that changes are automatically applied to the translation

And, of course, this process can also be applied to updates of translations. The software strings are exported from the translated software application, transformed and enforced via the dynamic link throughout all translated documentation. Now, that will save your colleagues a bunch of time.

Interested?

Flow can help you integrate this process into your documentation. Contact us  for more information.