Re: Gnumeric Documentation styleguide

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

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.
Do not omit articles.
Open Main Menu and select item.
Open the Main Menu and select an item.
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.
    *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

Prof. Dr. Andreas J. Guelzow

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]