NLA - Messages and documentation

Messages
Message Services
Substituting Variables in Messages
Documentation and Machine Readable Information
Documentation for Applications
Numenclature
NLA Documentation

Messages

Messages are the reactions of a software system to inform the initiator of the task (e.g. end-user) or supervisor (e.g. system operator). Even for system management personel at large non-English-speaking installations the English language is not sufficient. With the proliferation of departmental or personal systems this issue is of great importance. The wrong operator response to a misunderstood message at system level may cause severe damage.

Menus and panels are only a special form of messages. Generally the NLA issue is critical to the implementation of presentation services, since they form the user interface!

Messages should be numbered with the same number corresponding to the same meaning in different languages or even in different customized versions. This will permit easy searching of documentation in a particular user's language if the user is exposed to a problem in a language different from his own (for example, the IBM US maintenance team could be working on a problem occurring in Iceland). An option should be provided to remove message numbers at presentation time.

There must be no constraint or assumption on the length of messages. This editing process at presentation layer must also allow for code page translations, since the messages in a particular language may use a particular coding, which may not be the same as the one of the end-user (For example French messages in the coding used in France, but end-user is in Germany).

A different code page can also be used for the same language in different countries. Default messages in one language should be stored in the richest possible way for this language (use accented upper- and lower case letters in French, sharp-s and umlauts in German). Only during presentation, during code page and country adjusting phases should information be allowed to be removed or modified due to hardware limitations or country dependencies. And this must happen only on a copy of the required text.

Message Services

The output facilities for messages must be an NLA function and must not be left to applications or runtime systems (of programming languages). Only at the presentation level the language is defined. The language may vary during the course of a job or session. System managers may prefer US-English, where end-users need their national language.

The function provided must create message text based on the following parameters:

• message number
• prefix (this may be date and time)
• action indicator (information, yes/no-answer requested, anticipated answers requested)
• language and country of text to be presented
• output values for «customization» of the message text
• receiving parameters for answers

Anticipated answers to messages must be handled in the same way as keywords. That is, the national language form entered by the user must be «translated» to a form independent of language.

Analyzing answers to anticipated messages can be easily avoided by presenting choices to the user. Since choices are «positive statements», this method also would avoid ambiguity.

Message texts must not be imbedded in program code.

Parameters of the presentation should allow end-users to specify if the messages presented should contain:

• date and time
• message number

Also the language of the messages may be different from the language of data currently being working on (For example: while spell checking a French text, a Swiss-German may desire German messages).

Message texts must be organized in a structured manner, for example in a data base. The structure should reflect the hierarchical structure of

• System
• Runtime-support
• Application.

The structure also could be called message domains. This would ease customization of messages according to specific needs (for example system messages emerging in an end-user application).

These messages must be managed and allow installation cusomization. For example, it must be possible to apply IBM message updates without user-modification.

Substituting Variables in Messages

An NLA must not only allow for messages in different languages, but also must specify a general mechanism for modifying messages of system and user applications. Currently every application has to establish its own process of message handling such as variable substitution. This leads to very different presentations to the user [Daube-4, Arielli, HP-2].

Since the order of significant words or items in a message may differ from language to language, a means to represent symbolic values in the messages must be provided:

ENGLISH:  Value #01 of parameter #02 for routine #03 is
          invalid.  Valid values are #04.
GERMAN:   Für die Routine #03 ist der Parameter #02 mit dem Wert #01
          ungültig. Gültige Werte sind #04.
FRENCH:   Valeur #01 non permise pour le paramètre #02 par
          routine #03. Les valeurs permises sont #04.

Note:

Pay attention particularly to the second sentence here, where plurals would have to be replaced by singular, if #04 is substituted by only one item.

Hence any method setting up messages from building blocks will fail in any environment.

Documentation and Machine Readable Information

Where cultural differences exist, messages must be stored in the richest possible form. For example, Swiss-German does not use the sharp-s (ß) character of German, but instead uses the double-s (ss). The upper case of the sharp-s (ß) is two upper-case s's (SS). Therefore the stored form for the German example would serve for the presentation variants: lower-case and upper-case in German and Swiss-German: straße, STRASSE, strasse, STRASSE.

In the same manner, in some French-speaking environments, upper-case accented letters are not used, in spite of the fact that they are required in correct French spelling. Accents must always be stored. It is the richest possible form and not only a fancy feature: it is a way for example to distinguish «poisson salé» (salted fish) from «poisson sale» (dirty fish) - there are numerous examples.

Documentation for Applications

The documentation of applications must be provided, at least for a selection of National Language. Since very often an installation only supports parts of applications, it must be possible for them to customize the documentation. Therefore reference manuals and the like must be available in machine readable form.

Documentation in a particular language (e.g. German or US-English) may not be well received in a particular country (for example Switzerland or Great Britain), since special terms, jargon or spelling may not be the same. Hence installations may need to modify the documentation to meet the special conditions. Also it is frequently desirable to include local standards and guidelines in the documentation.

To achieve this goal, machine readable documentation should make use of

• International standards like SGML
• Hierarchical document structure
• «dummy imbeds» at places, where the author can foresee the need for customer addenda.

Nomenclature

As stated with keywords a coherent terminology or nomenclature is of vital importance. If the names of actions, objects and the like are not chosen carefully, a translation may become cumbersome and the result will be unusable.

Many words of the «computer jargon» are very sensitive to culture (fore example pop-up, pull-down, bug ). The same is true for icons used in presentation services.

Developers must be forced to use one common set of terms (glossary). This also should be made available to customers – ideally in the form of an on-line dictionary. The list of words in [IBM SC26-4351] is accepted as a starter set, but is by no means complete.

NLA Documentation

The NLA documentation must be generally available as soon as possible. In its interactions with third-party developers, IBM must stress the use of the National Language Architecture as an integral part and requirement of SAA. This will help overcome the problem of educating the third-party developers to the National Language issue.