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
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.
On Fri, Jun 26, 2009 at 4:30 AM, Andersen, Verner Engell
VEAverner.ander...@radiometer.dk 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
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
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
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,
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
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
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
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
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
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,
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
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
...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:
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
Combining advice, experience, sympathy, and grins:
http://geekandpoke.typepad.com/geekandpoke/
http://geekandpoke.typepad.com/geekandpoke/2009/06/what-geeks-love-part-2.html
___
Sheila Carlisle V: 425/ 486-2988 F: 425/ 483-3836
Axial
Now I need to write developer documentation, which doesn't make sense to
me. I just can't seem to get an handle on what these books should look like.
Have you consulted with your developer management to define what they
think should be in the documentation?
--
John Posada
Senior Technical
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
I'm having lots of difficulty setting up my TOC.
Item 1:
The logo in the Headers on the Master Pages, show up correctly in Master Pages,
but not in Body Pages.
Master Pages: Right Page, logo placed in top right corner. Left Page, logo
placed in top left corner.
Body Pages: Pages 1, 2 and 3
Within each Chapter and Appendix, Figure and Table titles use an auto-numbering
sequence.
The first Table in any Chapter/Appendix starts with the Chapter number of
Appendix letter, followed by a dash and then is numbered sequentially (followed
by a colon and a title). For example:
Chapter 1:
Alison Craig wrote:
I'm having lots of difficulty setting up my TOC.
Item 1:
The logo in the Headers on the Master Pages, show up correctly in
Master
Pages, but not in Body Pages.
Master Pages: Right Page, logo placed in top right corner. Left Page,
logo
placed in top left corner.
Based on what you didn't say, it doesn't sound as if you've set up the
book file to manage the $chapnum variable.
In the Book file, highlight the first Appendix, right-click, select
Numbering Chapter and set the tab to use Alpha characters and start
with 1/A. Apply it and save.
Then highlight
Alison Craig wrote:
The numbering style for Figures and Tables in CHAPTERS are as follows:
Figure#1 1 6A = F:Figure $chapnum\+n=1:
Figure#+ 1 6A = F:Figure $chapnum\+n+:
Table#1 1 6A = U:Table $chapnum\+n=1:
Table#+ 1 6A = U:Table $chapnum\+n+:
I used the same logic for the
Great, this worked, thanks! One page had a custom setting.
One problem down, 50 million to go...
Alison
-Original Message-
From: Combs, Richard [mailto:richard.co...@polycom.com]
Sent: Friday, June 26, 2009 11:00 AM
To: Alison Craig; framers@lists.frameusers.com
Subject: RE: FM9 TOC
In general I would agree with you, but...
Both I and my company are new to FrameMaker so that means - by definition -
there will be teething pains. I've been warned that the learning curve is steep.
Because I am setting up the initial TOC configuration and I have zero plans to
change it, it
This worked.
Thanks, Alison
-Original Message-
From: Art Campbell [mailto:art.campb...@gmail.com]
Sent: Friday, June 26, 2009 11:03 AM
To: Alison Craig
Cc: framers@lists.frameusers.com
Subject: Re: FM9 Figure and Table Title Auto-Number Errors
Based on what you didn't say, it doesn't
In my response to Alison's numbering query, I included one bit of real
stupidity. We corresponded off-list about it, but I thought I'd better
correct myself on-list before I confuse someone else.
The problem is in this part:
If it matters, my Appendix heading style (Heading1App) is
A:Appendix
Hi everyone,
I'm working in unstructured FrameMaker 8 (p277) on Windows XP, and I'm noticing
that tables have spacing issues at the bottom of a page when they have less
than twice the number of orphan rows.
For example, if I have a table with 3 rows (regardless of heading rows) that
has an
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
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
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
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
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
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
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
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
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
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
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
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:
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
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
"...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
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
Combining advice, experience, sympathy, and grins:
http://geekandpoke.typepad.com/geekandpoke/
http://geekandpoke.typepad.com/geekandpoke/2009/06/what-geeks-love-part-2.html
___
Sheila Carlisle V: 425/ 486-2988 F: 425/ 483-3836
Axial
> Now I need to write developer documentation, which doesn't make sense to
> me. ? I just can't seem to get an handle on what these books should look like.
>
Have you consulted with your developer management to define what they
think should be in the documentation?
--
John Posada
Senior
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
I'm having lots of difficulty setting up my TOC.
Item 1:
The logo in the Headers on the Master Pages, show up correctly in Master Pages,
but not in Body Pages.
Master Pages: Right Page, logo placed in top right corner. Left Page, logo
placed in top left corner.
Body Pages: Pages 1, 2 and 3
Within each Chapter and Appendix, Figure and Table titles use an auto-numbering
sequence.
The first Table in any Chapter/Appendix starts with the Chapter number of
Appendix letter, followed by a dash and then is numbered sequentially (followed
by a colon and a title). For example:
Chapter 1:
Alison Craig wrote:
> I'm having lots of difficulty setting up my TOC.
>
> Item 1:
>
> The logo in the Headers on the Master Pages, show up correctly in
Master
> Pages, but not in Body Pages.
>
> Master Pages: Right Page, logo placed in top right corner. Left Page,
logo
> placed in top left
Based on what you didn't say, it doesn't sound as if you've set up the
book file to manage the <$chapnum> variable.
In the Book file, highlight the first Appendix, right-click, select
Numbering > Chapter and set the tab to use Alpha characters and start
with 1/A. Apply it and save.
Then
Alison Craig wrote:
> The numbering style for Figures and Tables in CHAPTERS are as follows:
>
> Figure#1 1 6A = F:Figure
Great, this worked, thanks! One page had a "custom" setting.
One problem down, 50 million to go...
Alison
-Original Message-
From: Combs, Richard [mailto:richard.co...@polycom.com]
Sent: Friday, June 26, 2009 11:00 AM
To: Alison Craig; framers at lists.frameusers.com
Subject: RE: FM9
In general I would agree with you, but...
Both I and my company are new to FrameMaker so that means - by definition -
there will be teething pains. I've been warned that the learning curve is steep.
Because I am setting up the initial TOC configuration and I have zero plans to
change it, it
I fail to see how futzing with manual page breaks (the subject of the thread
and of Matt's reply, which was basically advising not to worry about those
"last 5%" details) has any bearing on the TOC setup, and particularly on
whether section numbers appear in the TOC. If you set up the section
This worked.
Thanks, Alison
-Original Message-
From: Art Campbell [mailto:art.campb...@gmail.com]
Sent: Friday, June 26, 2009 11:03 AM
To: Alison Craig
Cc: framers at lists.frameusers.com
Subject: Re: FM9 Figure and Table Title Auto-Number Errors
Based on what you didn't say, it
In my response to Alison's numbering query, I included one bit of real
stupidity. We corresponded off-list about it, but I thought I'd better
correct myself on-list before I confuse someone else.
The problem is in this part:
> > If it matters, my Appendix heading style (Heading1App) is
Hi everyone,
I'm working in unstructured FrameMaker 8 (p277) on Windows XP, and I'm noticing
that tables have spacing issues at the bottom of a page when they have less
than twice the number of orphan rows.
For example, if I have a table with 3 rows (regardless of heading rows) that
has an
59 matches
Mail list logo
