0

I am writing a technical documentation where I have to explain that you can name variables like "Name", "email", and "AGE". However, they cannot define another variable called "name" if "Name" is already defined.

My error message, in that case, reads like the following:

"Name" must be used in the same letter case.

The alternative could be something like the following:

"Name" must be used in the same capitalization.

What I am effectively trying do is to force case-insensitivity in a system that allows case-sensitivity. And I am not happy with either style of the error messages. case, for instance, might confuse some people. capitalization might sound weird if the original variable was itself called "name".

Is there a better/recommended way to write my error messages?

Thank you very much for your help!

3
  • i don't think your message matches the issue. If someone cannot use Name because NAME or name exists, then variables must be unique regardless of case, but the correct case must be used for existing variables.
    – jimm101
    Aug 18, 2018 at 18:25
  • @jimm101, you are correct. The message can be worded differently, as well. However, I believe the problem with explaining the case/capitalization is still there.
    – Vijay
    Aug 18, 2018 at 18:33
  • The technical term is case-sensitive. Most passwords are case-sensitive, and URIs are not case-sensitive on the server address, but they are for strings below it. Aug 18, 2018 at 22:49

1 Answer 1

1

A good error message allows the user to infer the cause and reason their way to a solution. For example:

Could not define “Name” because a variable with the same spelling has already been defined. Capital letters and lower-case letters are considered to be identical.

Ideally, a system should be based on a small set of design principles consistently applied. This allows the programmer to expose the principles in the error messages, which empowers the user to take reasonable corrective action.

In contrast, if the system is chaotic, or (worse) if it’s well-designed but its error messages appear as violations of arbitrary rules, the user is reduced to memorizing the system’s quirks and avoiding them, which in many cases will reduce the benefits that the system could have provided.

2
  • I think this is what I was looking for. I’ll use “spelling” and “capital and lower-case letters” in the message.
    – Vijay
    Aug 18, 2018 at 20:03
  • @Vijay Good luck with your project! Aug 18, 2018 at 20:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.