Re: Style guide feedback

["Kristin E Thomas" <kristint us ibm com>]

>> [1]"filename" and "file name" are a special illustrative case, where
>> the style guide allows both, making clear distinctions between when
>> each should be used for important reasons.

>I read the style guide, and I'm an experienced programmer. I didn't
>understand that there was a distinction between filename and file name. I
>thought the dual entries were an editorial mistake. I still don't
understand
>the distinction, and I can't imagine that it's a good idea to try to have
>two almost identical terms mean two different things. The important
reasons
>you speak of are opaque to me.

I think Darin has hit on a very common problem with style guides (including
the GNOME Style Guide).  There isn't always a lot of audience analysis when
a group puts out their style guide.  It's very important to distinguish
between whether a document is for a group of professional writers or a
group of people who are trained in another area but also write.  There are
very few cases when a style guide is written strictly for professional
writers, but often they are written in terms that are confusing even to
people who have closely studied grammar.  For example, in the GNOME style
guide it says not to use the "Saxon genitive."  I don't think this is a
term that most people, even professional writers, would understand.  I know
I didn't.

I would guess that Darin is a pretty good representative of a large group
of people that write for the GDP, so it might be worth taking another look
at some of the more grammatically technical language in the guide (I'm
thinking specifically about things like the discussion of gerunds).  If the
guide is confusing to people, they won't use it, and they'll let someone
else worry about it, creating more work for others and defeating the
purpose of having the guide at all.  Just my opinion.

Thanks,
Kristin


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Kristin Thomas
Linux Information Development
Linux Technology Center
Ph. (512) 838-4546
T/L 678-4546
Bldg. 908 1D002