Re: GNOME Documentation Style Guide

[John Fleck <jfleck inkstain net>]

On Tue, Jul 03, 2001 at 06:36:39PM -0400, Trevor Curtis wrote:
> I have one question:
> 
> "Writing for Localization: How to Write for Translation:
> 
> "Topic 3:
> Restrict the use of indefinite pronouns such as it, this and those,
> especially at the beginning of sentences.
> ...
> "Rewrite: The Menu Editor is a configuration tool for the Main
> Menu. The Menu Editor provides a useful way to set your system
> requirements. "
> 
> I understand how the above can be really helpful for someone
> translating docs, but in english this is a little bit
> clumsy. Sentences that repeat the proper noun when it isn't necessary
> seem, to me, incorrect, or at least "choppy". In the above example, it
> is obvious that the subject of the second sentence is the subject of
> the first sentence. In the other language I am familiar with, one
> would simply replace the proper noun with a pronoun as you would in
> english.
> 

I think the example Pat used illustrates the problem better than you
realize, Trevor.

Write the sentence this way:
"The Menu Editor is a configuration tool for the Main
Menu. It provides a useful way to set your system
requirements. "

"It" is ambiguous here. Does it refer to the "Menu Editor"? Or does it
refer to the "Main Menu"? A reader can probably figure it out by
context, but if you can remove the ambiguity, you save them the
trouble. You also save the risk that they figure it out wrong and
think the Main Menu can be used to set your system requirements. 

Cheers,
-- 
John Fleck
jfleck inkstain net (h), http://www.inkstain.net/fleck/