db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From <de...@mylevita.com>
Subject Re: [jira] Commented: (DERBY-1376) File java/engine/org/apache/derby/loc/messages_en.properties - Message XSLAT.D
Date Thu, 08 Jun 2006 05:26:07 GMT

----- Original Message ----
From: Laura Stewart <scotsmatrix@gmail.com>
To: derby-dev@db.apache.org
Sent: Wednesday, June 7, 2006 5:59:08 PM
Subject: Re: [jira] Commented: (DERBY-1376) File java/engine/org/apache/derby/loc/messages_en.properties
- Message XSLAT.D

 > *** (LS) While I like to be polite too, we are not sitting down to tea
> with the users :-) It is more professional in technical documentation to 
> leave the "Please" out. Besides, the key is not to be polite, but to
> provide the information that users need to resolve the problem.

Ah, I beg to differ.  I think that users too often are treated too 
brusquely in the way a system communicates with them.  I like the
metaphor that a system should act as a butler, ready to serve and always
polite.  I don't see anything wrong with "please" and using full 
sentences -- "The directory {0} is not empty" instead of "Directory {0}
not empty".  That's how robots in 1960s science fiction shows talk, not
people.  I think culturally we have been taught that software systems 
should sound like robots and be very formal, but I don't think it's
necessary or even what customers want.  
 *** (LS) I agree that we need full and complete sentences. We definitely want to avoid being
cryptic or brusk.  Additionally, one thing that I think we should avoid is any implication
that the user has done something wrong, to blame the user.  The "butler" would never say "It
is your fault Sir."  The "please" issue is one that I think should go through the "guidelines"
review.  See what the community thinks. 

 Thanks (he says politely),  
 *** (LS) Por nada Senor (she says with grace).


>     I think additional explanation is not  really required. User will see 
>     this error only when the s/he uses the logDevice attribute on the URL.
>     Thanks
>     -suresh
> --
> Laura Stewart


I agree with what you both are saying.  I think there's a difference though in saying please
and completing sentences.  Obviously we want to sound human, and not like a robot, and obviously
we want complete sentences.  But I agree with Laura about "Please" but for different reasons.
 To me, I think tech writers have moved away from using "please" because it implies that the
user has a choice.  "This doesn't work this way.  Please do it this way.  Or don't do it that
way, if you don't want to.  Its up to you."  Rather than put the please in there and make
it sound like there is a decision to make, if we remove the please, it sounds like a recommendation
to avoid the error.  "This doesn't work this way.  You can do it this way."  

I don't think its rude.  Its just straghtforward.  I dont think this is something we need
to harp on either, I just thought I'd join in on the discussion.  I do know we say "please"
in other areas in the book.  But that doesn't mean its what we should be saying in those places


View raw message