Re: Gnumeric Documentation styleguide

["Andreas J. Guelzow" <aguelzow taliesin ca>]

Alexander Kirillov wrote:

> It should be noted that there is such a thing as GDP Style Guide with
> very detailed instructions about the terms to use and not use, proper
> markup, etc (but not indenting or naming scheme for files). Most of the
> current gnumeric documentation is not even close to following this
> guide. You can see it at
> http://developer.gnome.org/documents/style-guide/index.html


Well, it is very difficult to be interested in readng a style guide that 
from the very outset seems to contain many examples of bad writing:

Just a random collection of examples:

The section "Who should read this book" does not try to answer that 
question. In fact the title seems to be the only(?) place were the guide 
is called a book. Otherwise it always seems to be a guide.

fundamentals.html: avoid jargon you haven't defined
but the style guide uses jargon itself without defining it. (Of course 
perhaps some of those terms only sound like jargon to a non-native 
english speaker: saxon genitive???)

"Do not use gerunds where a translator can mistake them for adjectives."
And how am I supposed to know which gerunds could be mistaken for 
adjectives by a translator to hungarian?

"Count the number of hard words of three syllables or more, HW." I can't 
know what this means:
Am I supposed to count all words of three syllables or more? But they 
wouldn't use unnecessary words. would they? THere fore there must be 
hard words of three syllables or more and those that aren't.  `hard 
words' ... undefined jargon?

And of course the section on the Flesh Readability Test (or is that: 
Flesch Reading Ease Scale?) says how we can calculate that value, it 
says what those numbers are supposed to mena and that for technical docs 
they tend to be low, but the necessary information to make this useful 
is missing: which score do we consider acceptable?

"Example 2. Rewrite 1:
Normally, the kernel does not immediately write file data to disk. It 
stores the data in memory, then periodically writes it to disk."
But elsewhere it says that if you find the word `it' rewrite the sentence!

In guidelinesfortechwriting.html:
"Example 5. Example 3"   no comment

"Topic 17
Use of articles.
Rule
Do not omit articles.
Example
Open Main Menu and select item.
Rewrite
Open the Main Menu and select an item.
Exception
None."
Am I mistaken or should that be: Do not omit any articles.
Or how is that differnet from the example?

"You also need to make sure that you do not inadvertently achieve 
non-objectives."  Pardon me?

"Problem areas:
    *Adherence to capitalization rules.
    *Use of inconsistent terminology."
shouldn't this be:
    *Adherence to capitalization rules.
    *Consistency terminology.
or
    *Failure to adhere to capitalization rules.
    *Use of inconsistent terminology."
or aren't we trying to be consisten?

"Do not abbreviate common units of measurements."
You would think that this isn't really meant. Why should we write
1.2 centimeters or 3.4 kilobytes?

I still don't know how to spell out 2.3 seconds.

Are third level headers/titles not headers anymore (at least the 
capitalization rule does not seem to apply anymore)

Independent from what any style guide says, when I write about 
statistical tests I will _not_ write 0.05 percent as a significance level!

According to the definition section a `field' is dialog element into 
which you must enter data according to a particular syntax or structure.
If we just ask for a title without any specific syntax requirements then 
it isn't a field any more??
And why does the example suddenly use entry field. Doesn't field alone 
suffice?


time to stop

Andreas
--
Prof. Dr. Andreas J. Guelzow
http://www.math.concordia.ab.ca/aguelzow