Whatever the product or service you market, your content is likely to refer to a software application. The software appears in the online help in the form of screenshots and UI (User Interface) terms and content managers struggle to manage them efficiently. The challenge increases with localization, which generally brings up several questions:

• Who manages the UI terms across all languages?
• How do we maintain the documentation across all languages?
• What about screenshots? Do we include them? Do we have them translated?
• How can we switch from a waterfall to an agile model to shorten the time to market?
• Are there standard solutions? What are the best practices?

The three typical silos involved in UI string management

Here are the most common silos, there can be additional ones:

• UI terms are usually written in English by the software development team, with little input from the other departments. Sometimes, a UX designer is involved.
• The localization manager hires external translators to translate the strings into other languages. They often work without a glossary or context.
• Technical writers may be distributed in several locations across the world and dealing with multiple product teams. The glossaries they create are not shared and terminology at the project level is managed to a certain degree.

The waterfall method still prevails in documentation

Documentation, online help, and software design take place concurrently; documentation and online help are finalized once the software is frozen to enable using the appropriate UI terms.

Upon software validation:

• Screenshots are inserted into the documentation and online help
• Software strings are translated
• Translated software is built, then tested, and the UI terms are frozen in the target languages
• Documentation and online help are translated.

A typical waterfall project plan for a mid-size software application looks like this:

Agile is the norm in software design

Agile is preferred in software because it facilitates collaboration, improves software quality, and shortens the time to market.

Applying agile to multilingual documentation

When documentation managers practice agile, they typically have the following schedule:

• Software features are available at sprint S.
• Corresponding online help is available at sprint S+1

Unfortunately, localization usually follows the traditional waterfall process and the time saved on creating the documentation is lost.

DITA Best Practices

• Review your DITA information model so that you can write the documentation without freezing the UI. Instead of writing UI strings in the literature, reference a shared DITA resource file (an XML file with string IDs and string values) using conkeyref (see our relevant post).
• Review your product design to cancel the build phase: Instead of building strings in the system, make sure your product can accept language packs (ideally an XML file with string IDs and string values).
• Manage the shared DITA resource file as your UI master data and generate the software language pack through a simple transformation. If you manage this file in your CCMS, you will also manage the translated versions.

A project plan reduced to weeks

Furthermore, User Experience is enhanced since the consistency of screenshots and UI terms is guaranteed in the documentation and the software.

Find out more about localizing images such as screenshots in this post.