Re: GDSG topic - grammar terms.

[Pat Costello <Patrick Costello sun com>]

I still say a short glossary is the most appropriate solution. There are few 
really "complex" terms in the current GDSG. 

Pat

> Subject: Re: GDSG topic - grammar terms.
> To: gnome-doc-list gnome org, Patrick Costello sun com
> X-MIMETrack: Serialize by Router on D04NMS81/04/M/IBM(Release 5.0.8 |June 18, 
2001) at 12/19/2001 09:57:46 AM
> MIME-Version: 1.0
> 
> >Upfront, I'd like to say that I have a thorough understanding of the
> grammar
> >terms specifically mentioned, namely "gerund" and "Saxon genitive". I am
> >completely comfortable with these terms, which perhaps leads me to
> overlook that
> >other people might not be so familiar with the terms. Nevertheless, I do
> >recommend we use correct terminology wherever possible in the GDSG, rather
> than
> >avoid unfamiliar concepts for fear that some contributors might not
> understand.
> >My preference would always be to use real grammar terms, backed up by
> examples
> >to help those contributors not familiar with the terms.
> >
> I too have a thorough understanding of and extensive experience with
> grammar, but I don't really think that is the point.  The point I was
> trying to raise was that if the audience for the Style Guide doesn't
> understand technical grammar terms, then the purpose of the Guide is lost.
> From what I've seen on this list, the majority of contributors to the GNOME
> Documentation Project are developers who write, not trained technical
> writers who develop code.  It has been pointed out by several developers on
> the list that some of the grammar terms in the Style Guide are confusing.
> In my experience, when developers are confused by a style issue, the last
> thing they do is conduct more research to understand the style guide.  The
> first thing they do is stop reading and disregard all of the guidelines in
> the style guide.
> 
> >I do concede, however, that less experienced writers might need additional
> 
> >explanations for some grammar terms, so I suggest that we include a short
> >glossary of such terms in the GDSG. There shouldn't be many terms in the
> grammar
> >glossary, so this section would not be a big overhead. The explanations
> can be
> >in layman's (Sax. gen.) language, such as the nice piece that Tom Musgrove
> found
> >about the Saxon genitive. A simple hyperlink to the glossary term would
> allow
> >the writer to quickly look up the term, without interfering (gerund) with
> the
> >flow of the main text.
> >
> Maybe a quick reference that explained complex grammatical concepts in
> terms of more simple ones would be helpful.  For example, Saxon Genitive
> could be found under "possessives," a term that I think many more people
> would be familiar with.  This technique is not unheard of.  In _The Chicago
> Manual of Style_, and industry standard for writers, the only entry for
> genitive falls under possessives.
> 
> >This approach requires a certain amount of work on the part of the
> aspiring
> >writer to learn the tools of the trade. In the long run, however, the
> approach
> >leads to a better understanding of the craft of technical writing, which
> can
> >only be beneficial for future GNOME documentation. More experienced
> writers
> >should not need to access the grammar glossary, but surely a simple
> hyperlink
> >would not disturb the flow of their understanding in text.
> >
> While I agree that people who want to write should learn the "tools of the
> trade," I would argue that knowledge of complex grammatical concepts is not
> one of the most important tools.  Certainly, it is important that a writer
> know basic punctuation rules, but knowing terms like "gerund" and "Saxon
> genitive" are not at the heart of the "craft of technical writing."  What
> is at the center of technical writing is audience analysis and
> communicating concepts in a manner that is meaningful and helpful to
> readers.  One of the key concepts in technical communication is that
> grammar is a slave to technical communication, not the foundation upon
> which it is built.
> 
> >If there are any other unfamiliar grammar terms in the GDSG, other than
> the two
> >points mentioned in the mail string, then let me know. I'll be most
> pleased to
> >put together easy-to-understand explanations for the proposed grammar
> glossary
> >in the GDSG.
> 
> My mention of those two terms in particular was meant to be an example of
> how the Style Guide might not be suitable for the audience it is supposed
> to be directed to.  The complex terms are not the problem but rather a
> symptom of the larger problem that the Style Guide may not be completely
> written for the audience it is supposed to serve.  I would be happy to
> offer my help in an effort to improve the Guide.  I would suggest picking
> specific people (so it would be more likely we would get a response) from
> the list to review the Style Guide and basing some revisions on their
> responses.  I think it would be well worth the effort if the result is a
> Style Guide that people are more likely to use.
> 
> Thanks,
> Kristin
> 
> 
> 
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Kristin Thomas
> Linux Information Development
> Linux Technology Center
> Ph. (512) 838-4546
> T/L 678-4546
> Bldg. 908 1D002
>