Writing for Localization

[Sydney Weidman <sydney weidman slmsoft com>]

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.