IMHO, clear error messages are KEY to acceptance in production
environments. I did an interview of about 30 DBAs a few years ago, and
they consistently listed clear error messages as higher priority than
almost anything else. The reason? They are constantly being pounded
with 99.99% uptime, and a down database is a REAL problem. A bad error
message can significantly impact the time that the database is down.
This combined with excellent trace facilities and diagnostics is what
customers seem to regularly ask for.
The problem often is that the engineer writing the code and thus
creating the error messages is down in the trenches and often can't see
the forest for the trees. Their messages are for themselves, not
necessarily for the customers.
I would love to see an approach where error messages are regularly
reviewed by the tech pubs folks, and preferably our users, and go
through a process of getting revised.
I also think it would be good to have guidelines for writing error
messages. I think they can be as simple as: "an error message should
talk to the user, not to the developer. The error should be explained
from the perspective of the user, a probable cause should be provided,
as well as a suggested course of action."
At one project in Sun you actually had an API that *required* you to
provide the error messages, the probable cause, and a recommended course
of action as three separate messages. Just to drive the point home.
I'd be happy to (a) start a Wiki with guidelines for writing error
messages and (b) participate in any kind of review we make of the error
messages. If you want to drive this error message review, Halley, that
would be *great*.
Thanks,
David
Halley Pacheco de Oliveira wrote:
Hi,
I'm translating the file
java/engine/org/apache/derby/loc/messages_en.properties and sometimes,
when I can't understand the meaning of a message, I search for the message in
the source code to
discover it's meaning.
The issue DERBY-1376 was open because I couldn't see any problem with the fact that
"Log directory
exists". The existence of a directory is not a problem by itself. When reading
the source code in
LogToFile.java file I saw the comment "// make sure log directory is empty",
and the message being
showed only if the log directory is not empty, not if it exists.
I know it is a minor problem, almost insignificant, but I'm also having
problems with others
messages when translating them.
For example, message "XIE06.S=Entity name was null." wasn't clear for me too,
and when I looked at
the source code I saw the comment "Raised if, the entity (ie table/view) for
import/export is
missing in the database.". So, again, the comment in the source code is easier
to understand than
the message being showed to the user. There are others like this one as, for
example, for the
message "XIE05.S=Data file cannot be null." the comment in the source code is
"Raised if, null is
passed for data file url."
For me the biggest problem to overcome has being the translation of the message
"XBM08.D=Could not
instantiage {0} StorageFactory class {1}." I just can't understand the meaning
of this telegraphic
message even reading the source code, shown below, and would appreciate if
someone could explain
it to me.
private PersistentService getPersistentService( final String className, String
subSubProtocol)
throws StandardException
{
if( className == null)
return null;
Class storageFactoryClass = null;
try
{
storageFactoryClass = Class.forName( className);
}
catch (Throwable e)
{
throw StandardException.newException(
SQLState.INSTANTIATE_STORAGE_FACTORY_ERROR,
e,
subSubProtocol, className);
}
return new StorageFactoryService( subSubProtocol, storageFactoryClass);
} // end of getPersistentService
The reason for me to write this email is to ask if someone at ASF revised these
messages, and if
someone agrees that it would be good to revise these messages, since they are
all that end users
have.
Thanks,
Halley
__________________________________________________
Fale com seus amigos de graça com o novo Yahoo! Messenger
http://br.messenger.yahoo.com/
