I just had a little fight with my boss over this topic (well, the boss always wins so I will do what he wants to be done) but I’d like to have the opinion of others about this:
We are making a complex application that will be used by expert users (like the one who manages the company backups).
I made an Advanced log, which contains 3 types of log:
- messages
- alerts
- errors
Every error is translated and handled by the GUI, so the user will always know why something went wrong. My concern is about the messages:
The main goal of those messages is to have a detailed idea of what is happening and help the expert user to solve problems by himself without calling for assistance.
To do this I log a message (that will remain in RAM only, with a max message count) for every little kind of stuff, like
Connecting to server
Connection successfully
Request file list from path XXX
Starting receiving file list
File list successfully received
This can help to know when a problem occurred and to determine who is guilty for it.
The main problem is: Our program is translated in more than 10 languages! Translating that HUGE amount of little messages will be expensive and it will be used only by some users. You can access to this messages list using an Advanced console panel, so it’s clear it’s for Advanced users.
My boss wants those messages to be translated, but he doesn’t want to spend a lot in translation, so he asked me to limit myself in using those messages.
If I limit myself this message log can become useless, but if we don’t translate it our program loses its “friendly, translated approach“.
What is the best thing to do? Pay more and translate everything? Limit message usage? Try to convince my boss that Advanced Users SHOULD know English?
2
What you need to do is to configure logging to serve both your needs and those of your boss. Thing is, you aren’t really forced to do what your boss asks (“Limit message usage”) in the code and completely deprive yourself of an option to do logging the way you want.
Any half-decent logging framework allows programmer to output log messages into different locations (if your current framework can’t, you have much much bigger problems than translation).
Configure your logging so that what is supposed to be desirable by your boss outputs into one location (file) and what you consider necessary, goes to another.
After that, show example of supposedly “boss-compliant” output to them and verify if this fits their needs.
Also, point them to example of “internally necessary” output and explain that it can be turned completely off by config change (your logging framework should allow that, and if it doesn’t, see above) and explain that turning it off would make it much harder and expensive to investigate issues that may occur during application use.
Logging configuration is the way to keep your options open: no matter what is decided initially, changing it later would involve only logging config, leaving the application untouched.
3
-
Don’t assume advanced users know English. I’m from France and spent a year working in a software development company where:
-
Many programmers were unable to read or write in English,
-
Most programmers hated to read or write in English.
Given that any programmer should know English, you easily see how expecting non-programmers to know English may become problematic (you can, on the other hand, expect that if your app is targeting, say, scientists).
-
-
Technical character of the messages may matter. I hardly see people I’ve told about above who were unable to read in English to dive in
/var/log/when a proxy server or bind9 don’t behave as expected. Very probably, they won’t even find the location of those logs, and even if those messages were localized, they are too technical for them.On the other hand, I expect software such as Microsoft Word to have detailed, localized messages when the app fails, but is only able to show me a message box which is at the same time clear, detailed and extremely helpful: “Microsoft Word failed to start, because it encountered an unexpected error.”
-
Don’t assume the requirements of the app. It’s not your job. It’s not the job of your boss. It’s your customers/end users who should be asked if they are fluent enough in English or if the log messages should be translated.
Shipping features you expect the users will use without letting them to decide is one of the reasons projects are late and above the originally expected cost, because you’re spending time and money on features that maybe nobody needs.
- Users tell their problems: “I’m an expert user but I don’t know English very well.”
- People from your company who work with end users gather/predict the statistics. “On 12 000 users, there are 1 500 of our users who may be interested in translated log messages, and 400 users who are totally interested.”
- Developers evaluate the effort needed. “We have over twelve hundred error messages, and it would take two days to make them dependent on the language. It will take additional two hours to integrate the work of the translators, and will take thirty minutes every time we have to add or change a message.”
- Translators evaluate the effort needed. “It would take us three weeks to translate those messages to ten languages.“
- Project managers evaluate the cost and schedule. “We have no chances to ship the support for Oracle for September 1st if we need to localize the log messages meanwhile.”
- Business decide. “It’s acceptable to spend a few months on translation, given that then, we will be able to assert that our product is 100% translated into ten languages. It may also boost our international sales by giving a strong benefit over our primary competitor.”
-
Separate logs which are intended to be read by the users from the logs which are intended to be read by developers during debug. Gnat already described that.
This will help you to avoid limiting log entries. Having detailed logs when the app runs in verbose mode is crucial to mitigate the cost of debugging.
You’ll also be able to write those messages differently. For example, log messages intended for the end user may contain information such as paths of the files, something you may consider too sensitive to include in developer-oriented logs. On the other hand, you shouldn’t include stack trace in end-user log messages, since this is too technical.
-
Take in account that translating actual messages is only a part of the effort. What is more importantly is that you’ll have to translate every new message and every change to the existent message. Given the ten languages factor, this involves a lot of effort and organization, and may quickly become overwhelming for a small team.
You may end up using more and more the developer-oriented log (since it takes minutes to create a message), and change log messages for end-user log only when you don’t have a choice (since it may easily take weeks).
4