[post 10 of DITA Loc Wire] 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

  1. Documentation, online help (OLH) and software design take place concurrently; documentation and OLH are finalized once the software is frozen to enable using the appropriate UI terms.
    Upon software validation:
  2. Screenshots are inserted into the documentation and OLH
  3. Software strings are translated
  4. Translated software is built, then tested, and the UI terms are frozen in the target languages
  5. Documentation and OLH are translated.

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

chart single sourcing agile


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.
Agile Project management in software Cos

Primary development method used in software development and IT organizations. Source HPe, 2017 online survey with 600 respondents.


Applying agile to multilingual documentation

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

  1. Software features are available at sprint S.
  2. 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

  1. 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).
  2. 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).
  3. 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

Agile gantt chart software online help
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 screenshots in our post 3 savvy ways to localize screen captures.