OT: Use of please in technical documentation and messages on screen

[Andersen, Verner Engell VEA]

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.

Re: OT: Use of please in technical documentation and messages on screen

[Writer]

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.

Re: OT: Use of please in technical documentation and messages on screen

[Milan Davidovic]

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
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: Use of please in technical documentation and messages on screen

[Mike Wickham]

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

[Fred Ridder]

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

[Fred Ridder]

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: OT: Use of please in technical documentation and messages on screen

[Art Campbell]

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
VEAverner.ander...@radiometer.dk 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

[Les Smalley]

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

[Reid Gray]

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

[Writer]

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

[Mike Wickham]

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

[Writer]

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

[Syed.Hosain]

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: OT: Use of please in technical documentation and messages on screen

[William Abernathy]

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.

RE: Use of please in technical documentation and messages on screen

[Kelly McDaniel]

...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

[Combs, Richard]

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: Developer documentation

[Sheila Carlisle]

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 InfoSolutions Inc. (Bothell, Washington)
Automated Publishing Solutions / XML Publishing Solutions
http://www.axialinfo.com http://www.miramo.com


-Original Message-

Now I need to write developer documentation 

If anyone has any advice, experience or sympathy, I'm open to all.

Thanks,
Carl Yorke

TAG Networks



___


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: Developer documentation

[John Posada]

 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 Writer
NYMetro STC President

Looking for the next gig.
___


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

[Flato, Gillian]

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.

FM9 TOC Problems

[Alison Craig]

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 all logos show up in the top right corner 
(incorrect for page 2). Page 4, logo shows up in top left corner (correct).




Item 2:

Formatting TOC Styles:

My consultant started setting this up but the styles wouldn't configure 
correctly. On Page TOC1 (15 of 15) in the Reference Pages, I have edited the 
last 8 lines on the page - without touching the stuff in the first 10 lines:

   $paratext $pagenum
   $paratext $pagenum
$paratext $pagenum
   $PARATEXT $PAGENUM
$PARATEXT $PAGENUM
openXmlElementId  $relfilename:$UniqueXmlElementId
$RelativeXmlElementId
openObjectId $relfilename:$ObjectType $ObjectId
$paratext $pagenum
$PARATEXT $PAGENUM
CHAPTER 1: $PARATEXT..$PAGENUM
   $PARANUM $PARATEXT...$PAGENUM
$paranum $paratext..$pagenum
  $paranum $paratext$pagenum
$CHAPNUM: $PARATEXT.$PAGENUM
   $PARANUM $PARATEXT...$PAGENUM
$paranum $paratext..$pagenum
  $paranum $paratext$pagenum

Note: There is a tab between $PARANUM $PARATEXT.


These last 8 lines should translate to the following, but they don't:

CHAPTER 1: INTRODUCTION..1-1
   1.1 Second Chapter Level..1-1
1.1.1 Third Chapter Level1-2
  1.1.1.1 Fourth Chapter Level...1-3
Appendix A: Safety...A-1
   A.1 Second Appendix Level.A-4
A.1.1 Third Appendix Level...A-5
  A.1.1.1 Fourth Appendix Level..A-5

The closest I come is the first line, but it isn't picking up the fact that the 
page number should be 1-1, instead it just says 1. None of the rest of the 
lines even recognize the tabs, let alone the tab with leader before the page 
number, although the page numbers are there as are the indentations at the 
beginning of the relevant lines.

Help would be most appreciated!

Alison
___


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.

FM9 Figure and Table Title Auto-Number Errors

[Alison Craig]

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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
auto-numbering has nothing to do with the section number numbering of 1.1, 
1.1.1, 1.1.1.1).

Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
auto-numbering has nothing to do with the section number numbering of A.1, 
A.1.1, A.1.1.1).


Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).

After a lot of reading and tweaking, I've managed to make this work perfectly 
in Chapters - but not in Appendices.

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 APPENDICES, but instead of getting Table A-1: 
Title, I get Table 1-1: Title, Table 1-2: Title. So they are numbering 
sequentially, just not with the Appendix letter.

After 3-1/2 years, I still don't have any Figures in the Appendices so I'll 
cross that bridge if I come to it at some in the future.

If it matters, my Appendix heading style (Heading1App) is A:Appendix A+: 
and my Appendix Table styles are as follows .

Table#A 1 6A = U:Table $chapnum\+n+:
Table#A+ 1 6A = U:Table $chapnum\+n+:


Does anyone have any idea what I am doing wrong?

Alison
___


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: FM9 TOC Problems

[Combs, Richard]

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.
 Body Pages: Pages 1, 2 and 3 all logos show up in the top right corner
 (incorrect for page 2). Page 4, logo shows up in top left corner
(correct).

Check what master page is applied to page 2 (Format  Page Layout 
Master Page Usage). Make sure it's Right/Left, not some Custom page (and
make sure the doc is set up as two-sided).
 
 Item 2:
 
 Formatting TOC Styles:
 
 My consultant started setting this up but the styles wouldn't
configure
 correctly. On Page TOC1 (15 of 15) in the Reference Pages, I have
edited
 the last 8 lines on the page - without touching the stuff in the
first 10
 lines:

The default page (and flow) name for the TOC spec is TOC, not TOC1.
That, plus the rather large number of ref pages, makes me suspect you've
got more than one TOC spec. 

BTW, if your consultant couldn't straighten out this mess and get your
TOC looking right in a couple of hours, you need a better consultant.


 
$paratext $pagenum
$paratext $pagenum
 $paratext $pagenum
$PARATEXT $PAGENUM
 $PARATEXT $PAGENUM
 openXmlElementId
 $relfilename:$UniqueXmlElementId
 $RelativeXmlElementId
 openObjectId $relfilename:$ObjectType $ObjectId
 $paratext $pagenum
 $PARATEXT $PAGENUM
 CHAPTER 1:
$PARATEXT..$PAGENUM
$PARANUM
$PARATEXT...$PAGENUM
 $paranum
$paratext..$pagenum
   $paranum
$paratext$pagenum
 $CHAPNUM:
$PARATEXT.$PAGENUM
$PARANUM
$PARATEXT...$PAGENUM
 $paranum
$paratext..$pagenum
   $paranum
$paratext$pagenum
 
 Note: There is a tab between $PARANUM $PARATEXT.

Ack! This is an unholy mess. The line beginning with openObjectId is
the ActiveTOC paragraph and should be the first thing in the TOC spec
flow. The paragraphs above that indicate that you've set up the TOC to
include pgfs from the docs in the book for which there was no
corresponding *TOC pgf in the TOC spec. 

Put the cursor in one of these lines and see what pgf format it is. They
all end in TOC and the preceding part is the name of the pgf format
for which it's used. For instance, the Head3TOC pgf is used for the TOC
entries that point to Head3 pgfs in your book. 

Since you have so many *TOC pgfs, I suspect some or all of the formatted
ones below the openObjectId line aren't being used. Maybe the heading
format names have changed since the TOC spec was set up. 

 These last 8 lines should translate to the following, but they don't:
 
 CHAPTER 1: INTRODUCTION..1-1
1.1 Second Chapter Level..1-1
 1.1.1 Third Chapter Level1-2
   1.1.1.1 Fourth Chapter Level...1-3
 Appendix A: Safety...A-1
A.1 Second Appendix Level.A-4
 A.1.1 Third Appendix Level...A-5
   A.1.1.1 Fourth Appendix Level..A-5
 
 The closest I come is the first line, but it isn't picking up the fact
that
 the page number should be 1-1, instead it just says 1. None of the
rest

Because the TOC spec specifies only $pagenum instead of
$chapnum-$pagenum. Since none of the TOC spec entries specify
$chapnum, it seems that this TOC spec was set up for continuous page
numbering, not folio (chapter-page) numbering. 

 of the lines even recognize the tabs, let alone the tab with leader
 before the page number, although the page numbers are there as are the
 indentations at the beginning of the relevant lines.

Because you haven't defined the *TOC pgf formats to have the correct
tabs and leaders. The pgfs at the bottom of the TOC spec seem to have
the tab and leader properly defined, which tends to confirm my earlier
suspicion that those formats aren't being used and the TOC spec wasn't
set up for the heading formats you're currently using. 

The problems you're having touch on several key areas that one needs to
understand to work effectively with FM -- pgf formatting, master page
layout and usage, document numbering settings, generated lists. I
strongly suggest that you get some training, work through the Classroom
in a Book or other tutorials, and/or spend a lot of quality time with
the user manual. 

HTH!
Richard


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
--
rgcombs AT gmailDOTcom
303-777-0436

Re: FM9 Figure and Table Title Auto-Number Errors

[Art Campbell]

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 the subsequent Appendix files, right-click, select
Numbering  Chapter and set the tab to use Alpha characters and
increment. Apply it and save.

Then update the book and see what it looks like.

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 1:37 PM, Alison
Craigalison.cr...@ultrasonix.com wrote:
 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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
 auto-numbering has nothing to do with the section number numbering of 1.1, 
 1.1.1, 1.1.1.1).

 Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
 auto-numbering has nothing to do with the section number numbering of A.1, 
 A.1.1, A.1.1.1).


 Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).

 After a lot of reading and tweaking, I've managed to make this work perfectly 
 in Chapters - but not in Appendices.

 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 APPENDICES, but instead of getting Table A-1: 
 Title, I get Table 1-1: Title, Table 1-2: Title. So they are numbering 
 sequentially, just not with the Appendix letter.

 After 3-1/2 years, I still don't have any Figures in the Appendices so I'll 
 cross that bridge if I come to it at some in the future.

 If it matters, my Appendix heading style (Heading1App) is A:Appendix A+: 
 and my Appendix Table styles are as follows .

 Table#A 1 6A = U:Table $chapnum\+n+:
 Table#A+ 1 6A = U:Table $chapnum\+n+:


 Does anyone have any idea what I am doing wrong?

 Alison
 ___


 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: FM9 Figure and Table Title Auto-Number Errors

[Combs, Richard]

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 APPENDICES, but instead of getting
Table A-
 1: Title, I get Table 1-1: Title, Table 1-2: Title. So they are
 numbering sequentially, just not with the Appendix letter.

The numbering settings for figures and tables are fine, both for
chapters and appendices. The problem is that chapter numbering isn't set
properly for the appendices. In the book window, select the first
appendix, right-click, and select Numbering. In the Numbering Properties
dialog, select the Chapter tab. Set Chapter # to 1 and Format to
ALPHABETIC (N). Then click Set. Verify that in subsequent appendices,
Chapter is set to Continue Numbering From Previous File in Book. Then
update the book, and everything should be fine. 
 
 After 3-1/2 years, I still don't have any Figures in the Appendices so
I'll
 cross that bridge if I come to it at some in the future.
 
 If it matters, my Appendix heading style (Heading1App) is A:Appendix
 A+: and my Appendix Table styles are as follows .
 
 Table#A 1 6A = U:Table $chapnum\+n+:
 Table#A+ 1 6A = U:Table $chapnum\+n+:

The A+ in the heading style means use upper-case alpha numbering --
it's the old way of doing things and works fine in this instance. But
I'd make it consistent with the rest of your numbering settings and
replace A+ with $chapnum so it's numbering is controlled by the
Chapter numbering settings, as I described above. 

And if you do that, you won't need a separate Heading1App for appendices
-- Heading1 will work just fine because the $chapnum variable will
have the appropriate value for whatever book component it's in. 

The information about numbering in the user manual (and help) does a
pretty decent job of explaining this stuff. 

HTH!
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: FM9 TOC Problems

[Alison Craig]

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 Problems

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.
 Body Pages: Pages 1, 2 and 3 all logos show up in the top right corner
 (incorrect for page 2). Page 4, logo shows up in top left corner
(correct).

Check what master page is applied to page 2 (Format  Page Layout 
Master Page Usage). Make sure it's Right/Left, not some Custom page (and
make sure the doc is set up as two-sided).
 
 Item 2:
 
 Formatting TOC Styles:
 
 My consultant started setting this up but the styles wouldn't
configure
 correctly. On Page TOC1 (15 of 15) in the Reference Pages, I have
edited
 the last 8 lines on the page - without touching the stuff in the
first 10
 lines:

The default page (and flow) name for the TOC spec is TOC, not TOC1.
That, plus the rather large number of ref pages, makes me suspect you've
got more than one TOC spec. 

BTW, if your consultant couldn't straighten out this mess and get your
TOC looking right in a couple of hours, you need a better consultant.


 
$paratext $pagenum
$paratext $pagenum
 $paratext $pagenum
$PARATEXT $PAGENUM
 $PARATEXT $PAGENUM
 openXmlElementId
 $relfilename:$UniqueXmlElementId
 $RelativeXmlElementId
 openObjectId $relfilename:$ObjectType $ObjectId
 $paratext $pagenum
 $PARATEXT $PAGENUM
 CHAPTER 1:
$PARATEXT..$PAGENUM
$PARANUM
$PARATEXT...$PAGENUM
 $paranum
$paratext..$pagenum
   $paranum
$paratext$pagenum
 $CHAPNUM:
$PARATEXT.$PAGENUM
$PARANUM
$PARATEXT...$PAGENUM
 $paranum
$paratext..$pagenum
   $paranum
$paratext$pagenum
 
 Note: There is a tab between $PARANUM $PARATEXT.

Ack! This is an unholy mess. The line beginning with openObjectId is
the ActiveTOC paragraph and should be the first thing in the TOC spec
flow. The paragraphs above that indicate that you've set up the TOC to
include pgfs from the docs in the book for which there was no
corresponding *TOC pgf in the TOC spec. 

Put the cursor in one of these lines and see what pgf format it is. They
all end in TOC and the preceding part is the name of the pgf format
for which it's used. For instance, the Head3TOC pgf is used for the TOC
entries that point to Head3 pgfs in your book. 

Since you have so many *TOC pgfs, I suspect some or all of the formatted
ones below the openObjectId line aren't being used. Maybe the heading
format names have changed since the TOC spec was set up. 

 These last 8 lines should translate to the following, but they don't:
 
 CHAPTER 1: INTRODUCTION..1-1
1.1 Second Chapter Level..1-1
 1.1.1 Third Chapter Level1-2
   1.1.1.1 Fourth Chapter Level...1-3
 Appendix A: Safety...A-1
A.1 Second Appendix Level.A-4
 A.1.1 Third Appendix Level...A-5
   A.1.1.1 Fourth Appendix Level..A-5
 
 The closest I come is the first line, but it isn't picking up the fact
that
 the page number should be 1-1, instead it just says 1. None of the
rest

Because the TOC spec specifies only $pagenum instead of
$chapnum-$pagenum. Since none of the TOC spec entries specify
$chapnum, it seems that this TOC spec was set up for continuous page
numbering, not folio (chapter-page) numbering. 

 of the lines even recognize the tabs, let alone the tab with leader
 before the page number, although the page numbers are there as are the
 indentations at the beginning of the relevant lines.

Because you haven't defined the *TOC pgf formats to have the correct
tabs and leaders. The pgfs at the bottom of the TOC spec seem to have
the tab and leader properly defined, which tends to confirm my earlier
suspicion that those formats aren't being used and the TOC spec wasn't
set up for the heading formats you're currently using. 

The problems you're having touch on several key areas that one needs to
understand to work effectively with FM -- pgf formatting, master page
layout and usage, document numbering settings, generated lists. I
strongly 

RE: Creating an FM9 Style to Apply Forced Page Breaks

[Alison Craig]

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 is worth the extra time and effort to get it right in the first 
place.

The products covered by the manuals have existed for some years and the format 
of the manual is not changing. This means the changeover needs to be seamless 
as far as our customers are concerned. Additionally, if the manual uses 
numbered sections with titles (1.1 Audience, 1.2 Manual Conventions, etc), not 
including this numbering in the TOC means the TOC information is incomplete and 
will degrade its usefulness.

So I will continue for a while longer...

Alison

 
-Original Message-
From: framers-boun...@lists.frameusers.com 
[mailto:framers-boun...@lists.frameusers.com] On Behalf Of Matt Sullivan
Sent: Thursday, June 25, 2009 9:40 PM
To: Alison Craig; 'William Abernathy'; framers@lists.frameusers.com
Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks

In class, and in practice, I preach the Design to 95% Perfect rule.

If I can't handle any of my numbering, referencing, and pagination at arm's
length in my template, then I let it go. In my world, a consistent and
predictable 95% perfect beats an inconsistent frustrating 100% perfectly
formatted document every time.

Of course, I also tell my clients that I can help with everything but the
politics...including a supervisor who wants to make Frame (and the authors)
jump through hoops all day long for trivial formatting issues.

I'd suggest you attach a dollar figure to the time associated with the extra
formatting, double-checking required by the formatting, and time associated
with discussing the formatting. If management feels that sacraficing that
money and productivity is worth the nominal improvement in the
documentation, there's not much you can do, short of looking for job
postings here...


-Matt

Matt Sullivan
GRAFIX Training

m...@roundpeg.com
www.roundpeg.com
Office 714 960-6840
Cell  text 714 585-2335
SMS message 7145852...@vtext.com

skype: mattatroundpeg
LinkedIn: http://www.linkedin.com/in/grafixtraining
facebook| plaxo

Click to tell me the social media sites you belong to


-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-boun...@lists.frameusers.com] On Behalf Of Alison Craig
Sent: Thursday, June 25, 2009 5:13 PM
To: William Abernathy; framers@lists.frameusers.com
Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks

I already use this method (for almost any kind of heading) - and I have
widow/Orphan control set to a more than just a couple of lines - but it
doesn't cover all situations.

Thanks, Alison

 

-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-boun...@lists.frameusers.com] On Behalf Of William Abernathy
Sent: Thursday, June 25, 2009 2:39 PM
To: framers@lists.frameusers.com
Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks

If you need to insert these breaks in running text for aesthetic reasons
(i.e., you don't want to have a heading and three lines of body text,
followed by a page break), consider using the Keep With Next Paragraph
exception in the paragraph definition. This is no more effort than inserting
a dummy paragraph to force the page break, and has the benefit of lower
maintenance -- If the upstream formatting changes, you stand a much better
chance of the break falling in a logical/aesthetic fashion than if you force
a break (either with a P-tag exception or by inserting a dummy paragraph).
Once either paragraph crosses the page boundary, the break is redrawn in a
way that looks good. I believe it is also possible to program this behavior
into your body text definition's Widow/Orphan Lines control, but I have not
investigated this.

--William

Alison Craig wrote:
 Is there a way to create a style that accepts all existing formatting and
 simply applies (i.e., forces) a page break? My attempts to create such a
 style have failed so far.
 
 I really don't want to have to create an Override every time I want a page
 break based on layout/esthetic reasons.
 
 Alison

___


You are currently subscribed to Framers as alison.cr...@ultrasonix.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/alison.craig%40ultrasoni
x.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 m...@grafixtraining.com.

Send list messages to fram...@lists.frameusers.com.

To unsubscribe send a blank email to 

RE: FM9 Figure and Table Title Auto-Number Errors

[Alison Craig]

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 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 the subsequent Appendix files, right-click, select
Numbering  Chapter and set the tab to use Alpha characters and
increment. Apply it and save.

Then update the book and see what it looks like.

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 1:37 PM, Alison
Craigalison.cr...@ultrasonix.com wrote:
 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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
 auto-numbering has nothing to do with the section number numbering of 1.1, 
 1.1.1, 1.1.1.1).

 Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
 auto-numbering has nothing to do with the section number numbering of A.1, 
 A.1.1, A.1.1.1).


 Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).

 After a lot of reading and tweaking, I've managed to make this work perfectly 
 in Chapters - but not in Appendices.

 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 APPENDICES, but instead of getting Table A-1: 
 Title, I get Table 1-1: Title, Table 1-2: Title. So they are numbering 
 sequentially, just not with the Appendix letter.

 After 3-1/2 years, I still don't have any Figures in the Appendices so I'll 
 cross that bridge if I come to it at some in the future.

 If it matters, my Appendix heading style (Heading1App) is A:Appendix A+: 
 and my Appendix Table styles are as follows .

 Table#A 1 6A = U:Table $chapnum\+n+:
 Table#A+ 1 6A = U:Table $chapnum\+n+:


 Does anyone have any idea what I am doing wrong?

 Alison
 ___


 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: FM9 Figure and Table Title Auto-Number Errors

[Combs, Richard]

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
  A+: and my Appendix Table styles are as follows .
 
  Table#A 1 6A = U:Table $chapnum\+n+:
  Table#A+ 1 6A = U:Table $chapnum\+n+:
 
 The A+ in the heading style means use upper-case alpha numbering
--
 it's the old way of doing things and works fine in this instance. But
 I'd make it consistent with the rest of your numbering settings and
 replace A+ with $chapnum so it's numbering is controlled by
the
 Chapter numbering settings, as I described above.
 
 And if you do that, you won't need a separate Heading1App for
appendices
 -- Heading1 will work just fine because the $chapnum variable will
 have the appropriate value for whatever book component it's in.

Umm ... yes, you do still need separate Heading1 and Heading1App pgfs.
The $chapnum variable will take care of changing 1 to A, but
nothing's going to automagically change the hardcoded text Chapter to
Appendix. Oops. 

(My excuse is that our template uses the same pgf tag for both because
its autonumber contains only the $chapnum variable, no text string. So
I didn't think...)

Sorry 'bout that! I'll slink away now and call it a week... 

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.

Strange orphan behavior in tables

[Andy Kass]

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 orphan setting of 2, the last 2 rows will move to the next page when 
there isn't space for the whole table. However, if the table moves down the 
page, or if that first row expands vertically, it jumps to the next page before 
it fills the whitespace below it.

In fact, after some testing, it appear that the whitespace below the first row 
can never be less than the height of the second row of the table. You can 
actually expand the second row of the table, the one after the page break, and 
cause the first row to jump after the break.

I don't have any keep with or start on settings on any of the rows, so I 
can't figure out what is causing this behavior. Has anyone else see this, is it 
a known bug? Is there a workaround?

Thanks,

  Andy

ak...@jaspersoft.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.

OT: Use of "please" in technical documentation and messages on screen

[Andersen, Verner Engell VEA]

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.

OT: Use of "please" in technical documentation and messages on screen

[Writer]

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.
>
>   

OT: Use of "please" in technical documentation and messages on screen

[Milan Davidovic]

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

[Mike Wickham]

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

Use of "please" in technical documentation and messages on screen

[Writer]

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.
> 
> 

Use of "please" in technical documentation and messages on screen

[Fred Ridder]

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

[Fred Ridder]

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"

OT: Use of "please" in technical documentation and messages on screen

[Art Campbell]

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

[Les Smalley]

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

Use of "please" in technical documentation and messages on screen

[Reid Gray]

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]

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.

Use of "please" in technical documentation and messages on screen

[Writer]

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.
> 
> 

Use of "please" in technical documentation and messages on screen

[syed.hos...@aeris.net]

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

[William Abernathy]

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

Use of "please" in technical documentation and messages on screen

[Kelly McDaniel]

"...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.

Use of "please" in technical documentation and messages on screen

[Combs, Richard]

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
--

Developer documentation

[Sheila Carlisle]

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 InfoSolutions Inc. (Bothell, Washington)
Automated Publishing Solutions / XML Publishing Solutions
http://www.axialinfo.com http://www.miramo.com


-Original Message-

Now I need to write developer documentation 

If anyone has any advice, experience or sympathy, I'm open to all.

Thanks,
Carl Yorke

TAG Networks

Developer documentation

[John Posada]

> 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 Writer
NYMetro STC President

Looking for the next gig.

Use of "please" in technical documentation and messages on screen

[Flato, Gillian]

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.

FM9 TOC Problems

[Alison Craig]

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 all logos show up in the top right corner 
(incorrect for page 2). Page 4, logo shows up in top left corner (correct).




Item 2:

Formatting TOC Styles:

My consultant started setting this up but the styles wouldn't configure 
correctly. On Page "TOC1 (15 of 15)" in the Reference Pages, I have edited the 
last 8 lines on the page - without touching the "stuff" in the first 10 lines:

   <$paratext> <$pagenum>
   <$paratext> <$pagenum>
<$paratext> <$pagenum>
   <$PARATEXT> <$PAGENUM>
<$PARATEXT> <$PAGENUM>
openXmlElementId  <$relfilename>:<$UniqueXmlElementId>
<$RelativeXmlElementId>
openObjectId <$relfilename>:<$ObjectType> <$ObjectId>
<$paratext> <$pagenum>
<$PARATEXT> <$PAGENUM>
CHAPTER 1: <$PARATEXT>..<$PAGENUM>
   <$PARANUM> <$PARATEXT>...<$PAGENUM>
<$paranum> <$paratext>..<$pagenum>
  <$paranum> <$paratext><$pagenum>
<$CHAPNUM>: <$PARATEXT>.<$PAGENUM>
   <$PARANUM> <$PARATEXT>...<$PAGENUM>
<$paranum> <$paratext>..<$pagenum>
  <$paranum> <$paratext><$pagenum>

Note: There is a tab between "<$PARANUM> <$PARATEXT>".


These last 8 lines should translate to the following, but they don't:

CHAPTER 1: INTRODUCTION..1-1
   1.1 Second Chapter Level..1-1
1.1.1 Third Chapter Level1-2
  1.1.1.1 Fourth Chapter Level...1-3
Appendix A: Safety...A-1
   A.1 Second Appendix Level.A-4
A.1.1 Third Appendix Level...A-5
  A.1.1.1 Fourth Appendix Level..A-5

The closest I come is the first line, but it isn't picking up the fact that the 
page number should be "1-1", instead it just says "1". None of the rest of the 
lines even recognize the tabs, let alone the "tab with leader" before the page 
number, although the page numbers are there as are the indentations at the 
beginning of the relevant lines.

Help would be most appreciated!

Alison

FM9 Figure and Table Title Auto-Number Errors

[Alison Craig]

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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
auto-numbering has nothing to do with the section number numbering of 1.1, 
1.1.1, 1.1.1.1).

Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
auto-numbering has nothing to do with the section number numbering of A.1, 
A.1.1, A.1.1.1).


Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).

After a lot of reading and tweaking, I've managed to make this work perfectly 
in Chapters - but not in Appendices.

The numbering style for Figures and Tables in CHAPTERS are as follows:

Figure#1 1 6A = F:Figure 

FM9 TOC Problems

[Combs, Richard]

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.
> Body Pages: Pages 1, 2 and 3 all logos show up in the top right corner
> (incorrect for page 2). Page 4, logo shows up in top left corner
(correct).

Check what master page is applied to page 2 (Format > Page Layout >
Master Page Usage). Make sure it's Right/Left, not some Custom page (and
make sure the doc is set up as two-sided).

> Item 2:
> 
> Formatting TOC Styles:
> 
> My consultant started setting this up but the styles wouldn't
configure
> correctly. On Page "TOC1 (15 of 15)" in the Reference Pages, I have
edited
> the last 8 lines on the page - without touching the "stuff" in the
first 10
> lines:

The default page (and flow) name for the TOC spec is "TOC," not "TOC1."
That, plus the rather large number of ref pages, makes me suspect you've
got more than one TOC spec. 

BTW, if your consultant couldn't straighten out this mess and get your
TOC looking right in a couple of hours, you need a better consultant.


> 
><$paratext> <$pagenum>
><$paratext> <$pagenum>
> <$paratext> <$pagenum>
><$PARATEXT> <$PAGENUM>
> <$PARATEXT> <$PAGENUM>
> openXmlElementId
> <$relfilename>:<$UniqueXmlElementId>
> <$RelativeXmlElementId>
> openObjectId <$relfilename>:<$ObjectType> <$ObjectId>
> <$paratext> <$pagenum>
> <$PARATEXT> <$PAGENUM>
> CHAPTER 1:
<$PARATEXT>..<$PAGENUM>
><$PARANUM>
<$PARATEXT>...<$PAGENUM>
> <$paranum>
<$paratext>..<$pagenum>
>   <$paranum>
<$paratext><$pagenum>
> <$CHAPNUM>:
<$PARATEXT>.<$PAGENUM>
><$PARANUM>
<$PARATEXT>...<$PAGENUM>
> <$paranum>
<$paratext>..<$pagenum>
>   <$paranum>
<$paratext><$pagenum>
> 
> Note: There is a tab between "<$PARANUM> <$PARATEXT>".

Ack! This is an unholy mess. The line beginning with "openObjectId" is
the ActiveTOC paragraph and should be the first thing in the TOC spec
flow. The paragraphs above that indicate that you've set up the TOC to
include pgfs from the docs in the book for which there was no
corresponding *TOC pgf in the TOC spec. 

Put the cursor in one of these lines and see what pgf format it is. They
all end in "TOC" and the preceding part is the name of the pgf format
for which it's used. For instance, the Head3TOC pgf is used for the TOC
entries that point to Head3 pgfs in your book. 

Since you have so many *TOC pgfs, I suspect some or all of the formatted
ones below the "openObjectId" line aren't being used. Maybe the heading
format names have changed since the TOC spec was set up. 

> These last 8 lines should translate to the following, but they don't:
> 
> CHAPTER 1: INTRODUCTION..1-1
>1.1 Second Chapter Level..1-1
> 1.1.1 Third Chapter Level1-2
>   1.1.1.1 Fourth Chapter Level...1-3
> Appendix A: Safety...A-1
>A.1 Second Appendix Level.A-4
> A.1.1 Third Appendix Level...A-5
>   A.1.1.1 Fourth Appendix Level..A-5
> 
> The closest I come is the first line, but it isn't picking up the fact
that
> the page number should be "1-1", instead it just says "1". None of the
rest

Because the TOC spec specifies only <$pagenum> instead of
<$chapnum>-<$pagenum>. Since none of the TOC spec entries specify
<$chapnum>, it seems that this TOC spec was set up for continuous page
numbering, not folio (chapter-page) numbering. 

> of the lines even recognize the tabs, let alone the "tab with leader"
> before the page number, although the page numbers are there as are the
> indentations at the beginning of the relevant lines.

Because you haven't defined the *TOC pgf formats to have the correct
tabs and leaders. The pgfs at the bottom of the TOC spec seem to have
the tab and leader properly defined, which tends to confirm my earlier
suspicion that those formats aren't being used and the TOC spec wasn't
set up for the heading formats you're currently using. 

The problems you're having touch on several key areas that one needs to
understand to work effectively with FM -- pgf formatting, master page
layout and usage, document numbering settings, generated lists. I
strongly suggest that you get some training, work through the "Classroom
in a Book" or other tutorials, and/or spend a lot of quality time with

FM9 Figure and Table Title Auto-Number Errors

[Art Campbell]

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 the subsequent Appendix files, right-click, select
Numbering > Chapter and set the tab to use Alpha characters and
increment. Apply it and save.

Then update the book and see what it looks like.

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 1:37 PM, Alison
Craig wrote:
> 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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
> auto-numbering has nothing to do with the section number numbering of 1.1, 
> 1.1.1, 1.1.1.1).
>
> Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
> auto-numbering has nothing to do with the section number numbering of A.1, 
> A.1.1, A.1.1.1).
>
>
> Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).
>
> After a lot of reading and tweaking, I've managed to make this work perfectly 
> in Chapters - but not in Appendices.
>
> The numbering style for Figures and Tables in CHAPTERS are as follows:
>
> Figure#1 1 6A = F:Figure 

FM9 Figure and Table Title Auto-Number Errors

[Combs, Richard]

Alison Craig wrote: 

> The numbering style for Figures and Tables in CHAPTERS are as follows:
> 
> Figure#1 1 6A = F:Figure 

FM9 TOC Problems

[Alison Craig]

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 TOC Problems

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.
> Body Pages: Pages 1, 2 and 3 all logos show up in the top right corner
> (incorrect for page 2). Page 4, logo shows up in top left corner
(correct).

Check what master page is applied to page 2 (Format > Page Layout >
Master Page Usage). Make sure it's Right/Left, not some Custom page (and
make sure the doc is set up as two-sided).

> Item 2:
> 
> Formatting TOC Styles:
> 
> My consultant started setting this up but the styles wouldn't
configure
> correctly. On Page "TOC1 (15 of 15)" in the Reference Pages, I have
edited
> the last 8 lines on the page - without touching the "stuff" in the
first 10
> lines:

The default page (and flow) name for the TOC spec is "TOC," not "TOC1."
That, plus the rather large number of ref pages, makes me suspect you've
got more than one TOC spec. 

BTW, if your consultant couldn't straighten out this mess and get your
TOC looking right in a couple of hours, you need a better consultant.


> 
><$paratext> <$pagenum>
><$paratext> <$pagenum>
> <$paratext> <$pagenum>
><$PARATEXT> <$PAGENUM>
> <$PARATEXT> <$PAGENUM>
> openXmlElementId
> <$relfilename>:<$UniqueXmlElementId>
> <$RelativeXmlElementId>
> openObjectId <$relfilename>:<$ObjectType> <$ObjectId>
> <$paratext> <$pagenum>
> <$PARATEXT> <$PAGENUM>
> CHAPTER 1:
<$PARATEXT>..<$PAGENUM>
><$PARANUM>
<$PARATEXT>...<$PAGENUM>
> <$paranum>
<$paratext>..<$pagenum>
>   <$paranum>
<$paratext><$pagenum>
> <$CHAPNUM>:
<$PARATEXT>.<$PAGENUM>
><$PARANUM>
<$PARATEXT>...<$PAGENUM>
> <$paranum>
<$paratext>..<$pagenum>
>   <$paranum>
<$paratext><$pagenum>
> 
> Note: There is a tab between "<$PARANUM> <$PARATEXT>".

Ack! This is an unholy mess. The line beginning with "openObjectId" is
the ActiveTOC paragraph and should be the first thing in the TOC spec
flow. The paragraphs above that indicate that you've set up the TOC to
include pgfs from the docs in the book for which there was no
corresponding *TOC pgf in the TOC spec. 

Put the cursor in one of these lines and see what pgf format it is. They
all end in "TOC" and the preceding part is the name of the pgf format
for which it's used. For instance, the Head3TOC pgf is used for the TOC
entries that point to Head3 pgfs in your book. 

Since you have so many *TOC pgfs, I suspect some or all of the formatted
ones below the "openObjectId" line aren't being used. Maybe the heading
format names have changed since the TOC spec was set up. 

> These last 8 lines should translate to the following, but they don't:
> 
> CHAPTER 1: INTRODUCTION..1-1
>1.1 Second Chapter Level..1-1
> 1.1.1 Third Chapter Level1-2
>   1.1.1.1 Fourth Chapter Level...1-3
> Appendix A: Safety...A-1
>A.1 Second Appendix Level.A-4
> A.1.1 Third Appendix Level...A-5
>   A.1.1.1 Fourth Appendix Level..A-5
> 
> The closest I come is the first line, but it isn't picking up the fact
that
> the page number should be "1-1", instead it just says "1". None of the
rest

Because the TOC spec specifies only <$pagenum> instead of
<$chapnum>-<$pagenum>. Since none of the TOC spec entries specify
<$chapnum>, it seems that this TOC spec was set up for continuous page
numbering, not folio (chapter-page) numbering. 

> of the lines even recognize the tabs, let alone the "tab with leader"
> before the page number, although the page numbers are there as are the
> indentations at the beginning of the relevant lines.

Because you haven't defined the *TOC pgf formats to have the correct
tabs and leaders. The pgfs at the bottom of the TOC spec seem to have
the tab and leader properly defined, which tends to confirm my earlier
suspicion that those formats aren't being used and the TOC spec wasn't
set up for the heading formats you're currently using. 

The problems you're having touch on 

Creating an FM9 Style to Apply Forced Page Breaks

[Alison Craig]

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 is worth the extra time and effort to get it right in the first 
place.

The products covered by the manuals have existed for some years and the format 
of the manual is not changing. This means the changeover needs to be seamless 
as far as our customers are concerned. Additionally, if the manual uses 
numbered sections with titles (1.1 Audience, 1.2 Manual Conventions, etc), not 
including this numbering in the TOC means the TOC information is incomplete and 
will degrade its usefulness.

So I will continue for a while longer...

Alison


-Original Message-
From: framers-bounces at lists.frameusers.com 
[mailto:framers-boun...@lists.frameusers.com] On Behalf Of Matt Sullivan
Sent: Thursday, June 25, 2009 9:40 PM
To: Alison Craig; 'William Abernathy'; framers at lists.frameusers.com
Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks

In class, and in practice, I preach the "Design to 95% Perfect" rule.

If I can't handle any of my numbering, referencing, and pagination at arm's
length in my template, then I let it go. In my world, a consistent and
predictable 95% perfect beats an inconsistent frustrating 100% perfectly
formatted document every time.

Of course, I also tell my clients that I can help with everything but the
politics...including a supervisor who wants to make Frame (and the authors)
jump through hoops all day long for trivial formatting issues.

I'd suggest you attach a dollar figure to the time associated with the extra
formatting, double-checking required by the formatting, and time associated
with discussing the formatting. If management feels that sacraficing that
money and productivity is worth the nominal improvement in the
documentation, there's not much you can do, short of looking for job
postings here...


-Matt

Matt Sullivan
GRAFIX Training

matt at roundpeg.com
www.roundpeg.com
Office 714 960-6840
Cell & text 714 585-2335
SMS message 7145852335 at vtext.com

skype: mattatroundpeg
LinkedIn: http://www.linkedin.com/in/grafixtraining
facebook| plaxo

Click to tell me the social media sites you belong to


-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Alison Craig
Sent: Thursday, June 25, 2009 5:13 PM
To: William Abernathy; framers at lists.frameusers.com
Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks

I already use this method (for almost any kind of heading) - and I have
widow/Orphan control set to a more than just a couple of lines - but it
doesn't cover all situations.

Thanks, Alison



-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of William Abernathy
Sent: Thursday, June 25, 2009 2:39 PM
To: framers at lists.frameusers.com
Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks

If you need to insert these breaks in running text for aesthetic reasons
(i.e., you don't want to have a heading and three lines of body text,
followed by a page break), consider using the "Keep With Next Paragraph"
exception in the paragraph definition. This is no more effort than inserting
a dummy paragraph to force the page break, and has the benefit of lower
maintenance -- If the upstream formatting changes, you stand a much better
chance of the break falling in a logical/aesthetic fashion than if you force
a break (either with a P-tag exception or by inserting a dummy paragraph).
Once either paragraph crosses the page boundary, the break is redrawn in a
way that looks good. I believe it is also possible to program this behavior
into your body text definition's Widow/Orphan Lines control, but I have not
investigated this.

--William

Alison Craig wrote:
> Is there a way to create a style that accepts all existing formatting and
> simply applies (i.e., forces) a page break? My attempts to create such a
> style have failed so far.
> 
> I really don't want to have to create an Override every time I want a page
> break based on layout/esthetic reasons.
> 
> Alison

___


You are currently subscribed to Framers as alison.craig at ultrasonix.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/alison.craig%40ultrasoni
x.com

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 matt at grafixtraining.com.

Send list messages to framers at 

Creating an FM9 Style to Apply Forced Page Breaks

[Fred Ridder]

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 numbering 
and the TOC template properly (neither of which is rocket science), you should 
never have to worry about them again even when the content changes.

-FR


> From: Alison.Craig at ultrasonix.com
> To: matt at grafixtraining.com; william at inch.com; framers at 
> lists.frameusers.com
> Date: Fri, 26 Jun 2009 14:13:40 -0700
> Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks
> 
> 
> 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 is worth the extra time and effort to get it right in the 
> first place.
> 
> The products covered by the manuals have existed for some years and the 
> format of the manual is not changing. This means the changeover needs to be 
> seamless as far as our customers are concerned. Additionally, if the manual 
> uses numbered sections with titles (1.1 Audience, 1.2 Manual Conventions, 
> etc), not including this numbering in the TOC means the TOC information is 
> incomplete and will degrade its usefulness.
> 
> So I will continue for a while longer...
> 
> Alison
> 
> 
> -Original Message-
> From: framers-bounces at lists.frameusers.com [mailto:framers-bounces at 
> lists.frameusers.com] On Behalf Of Matt Sullivan
> Sent: Thursday, June 25, 2009 9:40 PM
> To: Alison Craig; 'William Abernathy'; framers at lists.frameusers.com
> Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks
> 
> In class, and in practice, I preach the "Design to 95% Perfect" rule.
> 
> If I can't handle any of my numbering, referencing, and pagination at arm's
> length in my template, then I let it go. In my world, a consistent and
> predictable 95% perfect beats an inconsistent frustrating 100% perfectly
> formatted document every time.
> 
> Of course, I also tell my clients that I can help with everything but the
> politics...including a supervisor who wants to make Frame (and the authors)
> jump through hoops all day long for trivial formatting issues.
> 
> I'd suggest you attach a dollar figure to the time associated with the extra
> formatting, double-checking required by the formatting, and time associated
> with discussing the formatting. If management feels that sacraficing that
> money and productivity is worth the nominal improvement in the
> documentation, there's not much you can do, short of looking for job
> postings here...
> 
> 
> -Matt
> 
> Matt Sullivan
> GRAFIX Training
> 
> matt at roundpeg.com
> www.roundpeg.com
> Office 714 960-6840
> Cell & text 714 585-2335
> SMS message 7145852335 at vtext.com
> 
> skype: mattatroundpeg
> LinkedIn: http://www.linkedin.com/in/grafixtraining
> facebook| plaxo
> 
> Click to tell me the social media sites you belong to
> 
> 
> -Original Message-
> From: framers-bounces at lists.frameusers.com
> [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Alison Craig
> Sent: Thursday, June 25, 2009 5:13 PM
> To: William Abernathy; framers at lists.frameusers.com
> Subject: RE: Creating an FM9 Style to Apply Forced Page Breaks
> 
> I already use this method (for almost any kind of heading) - and I have
> widow/Orphan control set to a more than just a couple of lines - but it
> doesn't cover all situations.
> 
> Thanks, Alison
> 
> 
> 
> -Original Message-
> From: framers-bounces at lists.frameusers.com
> [mailto:framers-bounces at lists.frameusers.com] On Behalf Of William 
> Abernathy
> Sent: Thursday, June 25, 2009 2:39 PM
> To: framers at lists.frameusers.com
> Subject: Re: Creating an FM9 Style to Apply Forced Page Breaks
> 
> If you need to insert these breaks in running text for aesthetic reasons
> (i.e., you don't want to have a heading and three lines of body text,
> followed by a page break), consider using the "Keep With Next Paragraph"
> exception in the paragraph definition. This is no more effort than inserting
> a dummy paragraph to force the page break, and has the benefit of lower
> maintenance -- If the upstream formatting changes, you stand a much better
> chance of the break falling in a logical/aesthetic fashion than if you force
> a break (either with a P-tag exception or by inserting a dummy paragraph).
> Once either paragraph crosses the page boundary, the break is redrawn in a
> way that looks good. I believe it is also possible to program this behavior
> into your body text definition's Widow/Orphan Lines control, but I have not
> investigated this.
> 
> --William
> 
> Alison Craig wrote:
> > Is there a way to create a style 

FM9 Figure and Table Title Auto-Number Errors

[Alison Craig]

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 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 the subsequent Appendix files, right-click, select
Numbering > Chapter and set the tab to use Alpha characters and
increment. Apply it and save.

Then update the book and see what it looks like.

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 1:37 PM, Alison
Craig wrote:
> 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: Table 1-1: Title, Table 1-2: Title, etc. (fyi, the Figure 
> auto-numbering has nothing to do with the section number numbering of 1.1, 
> 1.1.1, 1.1.1.1).
>
> Appendix A: Table A-1: Title, Table A-2: Title, etc. (fyi, the Table 
> auto-numbering has nothing to do with the section number numbering of A.1, 
> A.1.1, A.1.1.1).
>
>
> Figures are numbered in the same way (Figure 1-1: Title, Figure 1-2: Title).
>
> After a lot of reading and tweaking, I've managed to make this work perfectly 
> in Chapters - but not in Appendices.
>
> The numbering style for Figures and Tables in CHAPTERS are as follows:
>
> Figure#1 1 6A = F:Figure 

FM9 Figure and Table Title Auto-Number Errors

[Combs, Richard]

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
> > :" and my Appendix Table styles are as follows .
> >
> > Table#A 1 6A = U:Table <$chapnum>\+:
> > Table#A+ 1 6A = U:Table <$chapnum>\+:
> 
> The "" in the heading style means use upper-case alpha numbering
--
> it's the old way of doing things and works fine in this instance. But
> I'd make it consistent with the rest of your numbering settings and
> replace "" with "<$chapnum>" so it's numbering is controlled by
the
> Chapter numbering settings, as I described above.
> 
> And if you do that, you won't need a separate Heading1App for
appendices
> -- Heading1 will work just fine because the <$chapnum> variable will
> have the appropriate value for whatever book component it's in.

Umm ... yes, you do still need separate Heading1 and Heading1App pgfs.
The <$chapnum> variable will take care of changing "1" to "A," but
nothing's going to automagically change the hardcoded text "Chapter" to
"Appendix." Oops. 

(My excuse is that our template uses the same pgf tag for both because
its autonumber contains only the <$chapnum> variable, no text string. So
I didn't think...)

Sorry 'bout that! I'll slink away now and call it a week... 

Richard


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
--
rgcombs AT gmailDOTcom
303-777-0436
--

Strange orphan behavior in tables

[Andy Kass]

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 orphan setting of 2, the last 2 rows will move to the next page when 
there isn't space for the whole table. However, if the table moves down the 
page, or if that first row expands vertically, it jumps to the next page before 
it fills the whitespace below it.

In fact, after some testing, it appear that the whitespace below the first row 
can never be less than the height of the second row of the table. You can 
actually expand the second row of the table, the one after the page break, and 
cause the first row to jump after the break.

I don't have any "keep with" or "start on" settings on any of the rows, so I 
can't figure out what is causing this behavior. Has anyone else see this, is it 
a known bug? Is there a workaround?

Thanks,

  Andy

akass at jaspersoft.com