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.andersen at radiometer.dk > ] > > Sent: Friday, June 26, 2009 4:31 AM > To: framers at 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 alan at alphabyte.co.nz. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/alan%40alphabyte.co.nz > > Send administrative questions to listadmin at 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
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
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.
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 at 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.
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-bounces at lists.frameusers.com] On Behalf Of Fred Ridder Sent: Friday, June 26, 2009 8:09 AM To: info at mikewickham.com; verner.andersen at radiometer.dk; framers at 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: info at mikewickham.com > To: verner.andersen at radiometer.dk; framers at 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 kmcdaniel at pavtech.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/kmcdaniel%40pavtech. com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
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.
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 --
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-bounces at 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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Fred Ridder" , "Frame Users" > 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 generic668 at yahoo.ca. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.c a > > Send administrative questions to listadmin at frameusers.com. > Visit > http://www.frameusers.com/ for more resources and > info. > > ___ You are currently subscribed to Framers as gflato at nanometrics.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/gflato%40nanometrics .com Send administrative questions to listadmin at 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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Fred Ridder" , "Frame Users" > 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.
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 at 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 rgray at interactivesupercomputing.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
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
OT: Use of "please" in technical documentation and messages on screen
I don't think that I'd write that, but it doesn't bother me at all. Better, I think, would be a message that says "Results are being updated..." Ideally with a spinning cursor or hourglass or bar graph line to show the progress. Art Campbell art.campbell at gmail.com "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 On Fri, Jun 26, 2009 at 4:30 AM, Andersen, Verner Engell VEA wrote: > 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 art.campbell at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. >
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: info at mikewickham.com; verner.andersen at radiometer.dk; framers at 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: info at mikewickham.com > To: verner.andersen at radiometer.dk; framers at 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"
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: info at mikewickham.com > To: verner.andersen at radiometer.dk; framers at 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"
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
"...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.
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.
Re: OT: Use of "please" in technical documentation and messages on screen
We've recently been reading some E.B. White books to our kids (Charlotte's Web and The Trumpet of the Swan) and I note that White has no practical respect for his own rules. I avoid "Please" in instructional documentation. The reader knows what to expect -- you're telling him or her how to make the product go, and the writer can venture forth from the indicative-mood explanations to imperative-mood commands without fear of offense. Cookbooks, for example, aren't lousy with "please," and would look downright weird if they were. I would not dismiss such small courtesies out of hand for user interfaces, however, because users and readers have different expectations. In an instruction from documentation, the writer is not burdening the reader, and the word "please" just lards up the sentence. When a computer application burns a few billion cycles and a few read-writes to disk working on a problem, however, it introduces a delay that importunes the user. Because the application is begging the user's indulgence while it does its work, it is in no position to bark out orders. In this instance, manners, even robotically generated ones, are entirely appropriate. --William Andersen, Verner Engell VEA wrote: > 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.
OT: Use of "please" in technical documentation and messages on screen
We've recently been reading some E.B. White books to our kids (Charlotte's Web and The Trumpet of the Swan) and I note that White has no practical respect for his own rules. I avoid "Please" in instructional documentation. The reader knows what to expect -- you're telling him or her how to make the product go, and the writer can venture forth from the indicative-mood explanations to imperative-mood commands without fear of offense. Cookbooks, for example, aren't lousy with "please," and would look downright weird if they were. I would not dismiss such small courtesies out of hand for user interfaces, however, because users and readers have different expectations. In an instruction from documentation, the writer is not burdening the reader, and the word "please" just lards up the sentence. When a computer application burns a few billion cycles and a few read-writes to disk working on a problem, however, it introduces a delay that importunes the user. Because the application is begging the user's indulgence while it does its work, it is in no position to bark out orders. In this instance, manners, even robotically generated ones, are entirely appropriate. --William Andersen, Verner Engell VEA wrote: > 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
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.
OT: Use of "please" in technical documentation and messages on screen
On Fri, Jun 26, 2009 at 4:30 AM, Andersen, Verner Engell VEA wrote: > 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. I've just opened the Windows Help and Support Center (XP), did a search for "please", and found 15 articles (full-text search results); each article contains at least one instance. Looking at the first few, none of them make me feel as though Microsoft were asking me for a favour. You could repeat this experiment with other help systems available to you. -- Milan Davidovic http://altmilan.blogspot.com
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
OT: Use of "please" in technical documentation and messages on screen
I say this from my North American English-speaker perspective... I prefer to take the Strunk and White approach to "omit needless words". Please is needless. As a user, I find the use of "please" patronizing. Personally, I would reword the message to say "Wait while the result list is updated". Nadine Andersen, Verner Engell VEA wrote: > 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 generic668 at yahoo.ca. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca > > Send administrative questions to listadmin at 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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Fred Ridder" , "Frame Users" > > 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.
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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Fred Ridder" , "Frame Users" 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 generic668 at yahoo.ca. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca > > Send administrative questions to listadmin at 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
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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Andersen, Verner Engell VEA" , "Frame > Users" > 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
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 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 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.
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 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
Re: OT: Use of "please" in technical documentation and messages on screen
I don't think that I'd write that, but it doesn't bother me at all. Better, I think, would be a message that says "Results are being updated..." Ideally with a spinning cursor or hourglass or bar graph line to show the progress. Art Campbell art.campb...@gmail.com "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 On Fri, Jun 26, 2009 at 4:30 AM, Andersen, Verner Engell VEA wrote: > 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 art.campb...@gmail.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/art.campbell%40gmail.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
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
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.
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 wrote: > From: Mike Wickham > Subject: Re: Use of "please" in technical documentation and messages on screen > To: "Andersen, Verner Engell VEA" , "Frame > Users" > 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 generic668 at yahoo.ca. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca > > Send administrative questions to listadmin at 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: OT: Use of "please" in technical documentation and messages on screen
On Fri, Jun 26, 2009 at 4:30 AM, Andersen, Verner Engell VEA wrote: > 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. I've just opened the Windows Help and Support Center (XP), did a search for "please", and found 15 articles (full-text search results); each article contains at least one instance. Looking at the first few, none of them make me feel as though Microsoft were asking me for a favour. You could repeat this experiment with other help systems available to you. -- Milan Davidovic http://altmilan.blogspot.com ___ 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: OT: Use of "please" in technical documentation and messages on screen
I say this from my North American English-speaker perspective... I prefer to take the Strunk and White approach to "omit needless words". Please is needless. As a user, I find the use of "please" patronizing. Personally, I would reword the message to say "Wait while the result list is updated". Nadine Andersen, Verner Engell VEA wrote: > 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 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.
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 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.
