Re: Writing for Localization

[Pat Costello <Patrick Costello Sun COM>]

Hi Syd, 

Thanks for your comments on the localization tips. The next time I do an update, 
I'll incorporate your comments. 

Pat

> Delivered-To: gnome-doc-list gnome org
> X-Accept-Language: en
> MIME-Version: 1.0
> Cc: docs gnome org
> Subject: Writing for Localization
> Content-Transfer-Encoding: 7bit
> X-BeenThere: gnome-doc-list gnome org
> X-Loop: gnome-doc-list gnome org
> X-Mailman-Version: 2.0.5
> List-Help: <mailto:gnome-doc-list-request gnome org?subject=help>
> List-Post: <mailto:gnome-doc-list gnome org>
> List-Subscribe: <http://mail.gnome.org/mailman/listinfo/gnome-doc-list>, 
<mailto:gnome-doc-list-request gnome org?subject=subscribe>
> List-Id: GNOME documentation issues <gnome-doc-list.gnome.org>
> List-Unsubscribe: <http://mail.gnome.org/mailman/listinfo/gnome-doc-list>, 
<mailto:gnome-doc-list-request gnome org?subject=unsubscribe>
> List-Archive: <http://mail.gnome.org/archives/gnome-doc-list/>
> 
> http://developer.gnome.org/documents/style-guide/chapter-1.html#CHAPTER-5
> 
> I really enjoyed reading the documentation in the style guide. I just
> wanted to comment on some minor points that I think may help make this
> particular page more readable.
> 
> First, the Topic titles seem to use inconsistent voice. Some topic
> titles begin with the word "Use" used as a noun, e.g. "Use of gerunds".
> Readers may confuse the noun form of the word with the verb form, even
> though the verb form is not grammatically correct. The confusion can be
> cleared up by using a definite article before the word "Use" e.g. "The
> use of gerunds".
> 
> As a result of this simple confusion, readers cannot predict what part
> of speech will anchor the other titles in the section. Will the titles
> be verb-based, or noun-based? Will they be subordinate clauses (as in
> "The use of gerunds") or complete sentences based on imperatives (as in
> "Use gerunds"). The initial confusion over verb and noun forms of the
> same word sets up further ambiguity in later uses. The Example ("In the
> properties dialog set:") in Topic 7 ("How to introduce lists and
> procedures"), uses the word "set" in a context which could be read as
> both a noun and a verb. The phrase "In the properties dialog set" could
> be introducing a list of items which are members of the set known as the
> "properties dialog set". This clouds the intended reading, which seems
> to be "In the properties dialog you can set the following properties:".
> The Rewrite does not completely eliminate the ambiguity.
> 
> The title of Topic 7 provides another example of ambiguous word choice.
> The title reads "Coordinate structures within a sentence". To
> geographers and mathematicians, the primary usage of "coordinate" might
> be as an adjective rather than as a verb. The preceding topics do not
> establish a pattern which would enable a reader to distinguish which of
> the two meanings the writer intended. The reader may wonder "Are the
> topic titles complete sentences (imperatives with implied subject) or
> are they just sentence fragments (subordinate clauses)?"
> 
> Other than these few small points, the material in the style guide is
> truly wonderful.
> 
> Thanks for all your hard work.
> 
> Regards,
> Syd.
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list