RE: Use of please in technical documentation and messages on screen
Verner, I write in Controlled English for translation. I would write: Wait while the program updates the results. Thus, you avoid the Please and the gerund (updating), the first of which is unnecessary and the second of which may not be translatable in many languages. Simple, direct, active voice statements are best. Words like carefully, slowly, etc., are also invitations to interpretation by the reader, which may not be the result you want. HTH. Tom -Original Message- From: Andersen, Verner Engell VEA [mailto:verner.ander...@radiometer.dk] Sent: Friday, June 26, 2009 4:31 AM To: framers@lists.frameusers.com Subject: OT: Use of please in technical documentation and messages on screen Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner Radiometer Medical ApS Akandevej 21 2700 Bronshoj Denmark Phone: +45 38 27 38 27 CVR: 27 50 91 85 Please be advised that this email may contain confidential information. If you are not the intended recipient, please do not read, copy or re-transmit this email. If you have received this email in error, please notify us by email by replying to the sender and by telephone (call us collect at +1 202-828-0850) and delete this message and any attachments. Thank you in advance for your cooperation and assistance. In addition, Danaher and its subsidiaries disclaim that the content of this email constitutes an offer to enter into, or the acceptance of, any contract or agreement or any amendment thereto; provided that the foregoing disclaimer does not invalidate the binding effect of any digital or other electronic reproduction of a manual signature that is included in any attachment to this email. This e-mail message from Cross Match Technologies, Inc. is intended only for the individual or entity to which it is addressed. This e-mail may contain information that is privileged, confidential and exempt from disclosure under applicable law. If you are not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you received this e-mail by accident, please notify the sender immediately and destroy this e-mail and all copies of it. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
On the other hand, why is it that computer programs must be seen to be terse/rude? There is no reason why a computer generated request cannot be perceived as, at least, courteous. Please wait is not a difficult thing to understand and is better for the user to read than a terse wait. It is not relevant that it may not be translatable into other languages. Users will be reading it in English, the language it is written in. Alan On 30/06/2009, at 1:26 AM, Thomas Scalise wrote: Verner, I write in Controlled English for translation. I would write: Wait while the program updates the results. Thus, you avoid the Please and the gerund (updating), the first of which is unnecessary and the second of which may not be translatable in many languages. Simple, direct, active voice statements are best. Words like carefully, slowly, etc., are also invitations to interpretation by the reader, which may not be the result you want. HTH. Tom -Original Message- From: Andersen, Verner Engell VEA [mailto:verner.ander...@radiometer.dk ] Sent: Friday, June 26, 2009 4:31 AM To: framers@lists.frameusers.com Subject: OT: Use of please in technical documentation and messages on screen Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner Radiometer Medical ApS Akandevej 21 2700 Bronshoj Denmark Phone: +45 38 27 38 27 CVR: 27 50 91 85 Please be advised that this email may contain confidential information. If you are not the intended recipient, please do not read, copy or re-transmit this email. If you have received this email in error, please notify us by email by replying to the sender and by telephone (call us collect at +1 202-828-0850) and delete this message and any attachments. Thank you in advance for your cooperation and assistance. In addition, Danaher and its subsidiaries disclaim that the content of this email constitutes an offer to enter into, or the acceptance of, any contract or agreement or any amendment thereto; provided that the foregoing disclaimer does not invalidate the binding effect of any digital or other electronic reproduction of a manual signature that is included in any attachment to this email. This e-mail message from Cross Match Technologies, Inc. is intended only for the individual or entity to which it is addressed. This e-mail may contain information that is privileged, confidential and exempt from disclosure under applicable law. If you are not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you received this e-mail by accident, please notify the sender immediately and destroy this e-mail and all copies of it. ___ You are currently subscribed to Framers as a...@alphabyte.co.nz. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/alan%40alphabyte.co.nz Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. -- Alan Litchfield MBus (Hons), MNZCS AlphaByte PO Box 1941, Auckland http://www.alphabyte.co.nz ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. -Fred Ridder From: i...@mikewickham.com To: verner.ander...@radiometer.dk; framers@lists.FrameUsers.com Subject: Re: Use of please in technical documentation and messages on screen Date: Fri, 26 Jun 2009 07:24:19 -0500 I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
Make that ...putting words in the mouth... rather than punning. Insufficient caffiene. -FR From: docu...@hotmail.com To: i...@mikewickham.com; verner.ander...@radiometer.dk; framers@lists.frameusers.com Subject: RE: Use of please in technical documentation and messages on screen Date: Fri, 26 Jun 2009 09:08:43 -0400 But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. -Fred Ridder From: i...@mikewickham.com To: verner.ander...@radiometer.dk; framers@lists.FrameUsers.com Subject: Re: Use of please in technical documentation and messages on screen Date: Fri, 26 Jun 2009 07:24:19 -0500 I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
I prefer active voice as well. An option that avoids please is to give the user an indication of how long a wait is expected, especially if it is a lengthy operation: We are updating the result list, this will take XX minutes... -- Les Smalley --- On Fri, 6/26/09, Mike Wickham i...@mikewickham.com wrote: I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
For status messages such as the one you cite below, I think using please is perfectly okay. I also agree with omitting words that add nothing to the meaning of the sentence; however, the use of please can convey a specific and useful tone. It's not inappropriate for a status or feedback alert message. That said, if in a distinct case we are directing the user to perform a specific action (procedural documentation), it's true we don't want the tone to sound as if we are begging. Example: Please back up your configuration file before you edit it. (Too soft, sounds optional) Back up your configuration file before you edit it. [Period.] Rules are good, but who hasn't said first you learn the rules...and then you learn to break them [in exceptional cases]? --E.B. White himself might have uttered this once or twice. -Original Message- From: framers-boun...@lists.frameusers.com on behalf of Andersen, Verner Engell VEA Sent: Fri 6/26/2009 4:30 AM To: framers@lists.frameusers.com Subject: OT: Use of please in technical documentation and messages on screen Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner Radiometer Medical ApS Akandevej 21 2700 Bronshoj Denmark Phone: +45 38 27 38 27 CVR: 27 50 91 85 Please be advised that this email may contain confidential information. If you are not the intended recipient, please do not read, copy or re-transmit this email. If you have received this email in error, please notify us by email by replying to the sender and by telephone (call us collect at +1 202-828-0850) and delete this message and any attachments. Thank you in advance for your cooperation and assistance. In addition, Danaher and its subsidiaries disclaim that the content of this email constitutes an offer to enter into, or the acceptance of, any contract or agreement or any amendment thereto; provided that the foregoing disclaimer does not invalidate the binding effect of any digital or other electronic reproduction of a manual signature that is included in any attachment to this email. ___ You are currently subscribed to Framers as rg...@interactivesupercomputing.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
I dislike the passive voice, but I dislike software anthropomorphism more. Who is we? Software elves? The little ghosts in the machine? Sounds more like Pac Man. Nadine --- On Fri, 6/26/09, Mike Wickham i...@mikewickham.com wrote: From: Mike Wickham i...@mikewickham.com Subject: Re: Use of please in technical documentation and messages on screen To: Andersen, Verner Engell VEA verner.ander...@radiometer.dk, Frame Users framers@lists.FrameUsers.com Received: Friday, June 26, 2009, 8:24 AM I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait Best regards, Verner ___ You are currently subscribed to Framers as generic...@yahoo.ca. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
Actually, the way I would write the message avoids passive voice and omits needless words. I would write, Updating result list. Please wait... Mike Wickham - Original Message - But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Use of please in technical documentation and messages on screen
Microsoft Word would chide you for using a sentence fragment. =D Nadine --- On Fri, 6/26/09, Mike Wickham i...@mikewickham.com wrote: From: Mike Wickham i...@mikewickham.com Subject: Re: Use of please in technical documentation and messages on screen To: Fred Ridder docu...@hotmail.com, Frame Users framers@lists.FrameUsers.com Received: Friday, June 26, 2009, 9:39 AM Actually, the way I would write the message avoids passive voice and omits needless words. I would write, Updating result list. Please wait... Mike Wickham - Original Message - But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. ___ You are currently subscribed to Framers as generic...@yahoo.ca. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
Mike Wickham wrote: Actually, the way I would write the message avoids passive voice and omits needless words. I would write, Updating result list. Please wait... This is how I'd do it too ... :) Z ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
...at worst, it is punning words in the mouth of the company,... I just love language...Kelly. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Fred Ridder Sent: Friday, June 26, 2009 8:09 AM To: i...@mikewickham.com; verner.ander...@radiometer.dk; framers@lists.frameusers.com Subject: RE: Use of please in technical documentation and messages on screen But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. -Fred Ridder From: i...@mikewickham.com To: verner.ander...@radiometer.dk; framers@lists.FrameUsers.com Subject: Re: Use of please in technical documentation and messages on screen Date: Fri, 26 Jun 2009 07:24:19 -0500 I don't know about the rules of technical documentation, but please wait sounds much better than just a command to wait. More importantly, I love that you didn't use passive voice. You used updating the result list instead of the typical, the result list is being updated. Bravo! Mike Wickham - Original Message - Hi Once I learned that you shouln't use the word please in technical documentation - that it was like asking the reader to do you favor. Does this still hold true? Is it OK to have this message displayed on the screen of our user interface? We are updating the result list, please wait ___ You are currently subscribed to Framers as kmcdan...@pavtech.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/kmcdaniel%40pavtech. com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
Syed.Hosain wrote: Mike Wickham wrote: Actually, the way I would write the message avoids passive voice and omits needless words. I would write, Updating result list. Please wait... This is how I'd do it too ... :) Likewise. And it's how Microsoft often does such status messages, so I don't think they'd chide you. There's nothing wrong with using sentence fragments in display (rather than narrative) text, like status and error messages, labels, tooltips, etc. Or you could think of Updating result list as a complete sentence with an understood/implied subject. :-) Richard Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 -- ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Use of please in technical documentation and messages on screen
Why not use the name of the software in the message instead of We. So, for example, if you are using a software called Ender Wiggens, state: Wait while Ender Wiggens updates the database. This avoids unclear pronouns, passive voice, and has a clear antecedent. -Gillian -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Writer Sent: Friday, June 26, 2009 6:52 AM To: Fred Ridder; Frame Users; Mike Wickham Subject: Re: Use of please in technical documentation and messages on screen Microsoft Word would chide you for using a sentence fragment. =D Nadine --- On Fri, 6/26/09, Mike Wickham i...@mikewickham.com wrote: From: Mike Wickham i...@mikewickham.com Subject: Re: Use of please in technical documentation and messages on screen To: Fred Ridder docu...@hotmail.com, Frame Users framers@lists.FrameUsers.com Received: Friday, June 26, 2009, 9:39 AM Actually, the way I would write the message avoids passive voice and omits needless words. I would write, Updating result list. Please wait... Mike Wickham - Original Message - But in order to avoid the passive voice, the UI resorts to the first person plural, which is also discouraged in most technical writing style guides. At best, the pronoun is unclear because it does not have a clear antecedent; at worst, it is punning words in the mouth of the company, which can potentially have lkegal consequences (at least in a litigious society like the US). This is one of the occasions where the passive voice is actually appropriate, because it is inconsequential to the user who or what is performing the act. All that really matters to the user is that the process is occurring. ___ You are currently subscribed to Framers as generic...@yahoo.ca. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.c a Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as gfl...@nanometrics.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/gflato%40nanometrics .com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
