Separate the Text from the Code

Documenting all the inputs and outputs is a good strategy when developing a web application. Every piece of textual content should also be identified and stored centrally. This leads to consistency and means identical text can be replaced globally and alternative translations provided more easily. Remember, the context is always important in the decision how to split up text, and how to translate it.

The text of instruction, confirmation and error messages should be handled in the same way... and of course it needs to be changed to something appropriate. I came across the following rather unhelpful message in a Siebel customer relationship management system:

The users of this public system are about as likely to have its documentation to refer to as go on a trip to the moon. Perhaps during development and acceptance testing, not all possible conditions were tested, so what else wasn't checked? It seems this should instead say something like:

Of course, telling the user first there is some sort of length limitation would be better. If all such pieces of text are located in a single repository (database table, configuration file, and so on), it can be easier to ensure that any system defaults are replaced with user-friendly and understandable messages. The only saving grace here is that the message implies the system might be doing some sort of type, length checks on data input by users.

A reminder for auditors: check what default text is stored in a system. And, make sure that changes to these text items follow a change control process.

When output text is scattered through developer's code, it is not usually a good sign. Using development frameworks that already have secure and tested error handling modules and separate the logic from words and layout are the way forward.

Update 19th November 2008: Christian Watson has posted a message about Error Message Design Showcase in his SmileyCat Web Design Blog giving an overview of how many sites handle the display of form entry error messages.