style: Ami's forwarded message


Previous by date: 10 Apr 2002 19:12:51 -0000 test, Joy Y Goodreau
Next by date: 10 Apr 2002 19:12:51 -0000 audience, Joy Y Goodreau
Previous in thread:
Next in thread:

Subject: Ami's forwarded message
From: "Joy Y Goodreau" ####@####.####
Date: 10 Apr 2002 19:12:51 -0000
Message-Id: <OFAB476BEA.B6BE665F-ON85256B97.00692447@pok.ibm.com>

This is the forward of Ami's email that she sent on Monday when the style
list was down. If I sent this to you individually, you may have already
read it.

joy


Joy Yokley Goodreau
Linux Information Developer
LDP Collections Editor
Ofc. (512) 838-4118
T/L 678-4118
####@####.####

----- Forwarded by Joy Y Goodreau/Austin/IBM on 04/09/2002 08:44 AM -----

                      "Ami M.

                      Echeverri"               To:       Joy Y
Goodreau/Austin/IBM@IBMUS
                      <simbuttercup@yah        cc:

                      oo.com>                  Subject:  project scope


                      04/08/2002 01:55

                      PM






As I read the initial discussion on this list (Joy and
David), the thought that strikes me first is that we
need a concensus on this project's scope.

Style guide implies different things to different
people. I imagine that some of us are thinking of a
comprehensive style guide in which we describe
language style, grammar, preferred terms and spelling,
formats, etc. Others might be thinking of something
less ambitious. And still others might be looking at
these scopes in abject horror.

So what exactly is the scope of this project? I think
that are at least two important questions we need to
consider:

1. What do we want to accomplish with the style guide?
Do we want to create a guide that will eventually
allow LDP to maintain a stylistically (is that a
word?) consistent set of documentation? That is,
rigid? Or do we want to provide tips and guidelines
and suggestions, but have the documentation retain the
authors' individual style (chatty, formal, somewhere
in between, whatever)?

2. How do we expect authors and editors to use the
style guide? Will authors read the guide before
writing? Will authors just write and then have editors
rewrite to bring the doc into conformity?

I'm concerned that we not create a style guide that
authors view as an impediment to writing. At the same
time, there's really no use in authors writing docs
with language and style that are too obscure for a
significant number of readers.

My suggestion for project scope is something I do at
my office. I reviewed many commercial style guides and
selected three of them. I then wrote a company style
guide that included the following:

1. Company-specific information like trademark info,
templates, etc.

2. References to the three books I chose.

3. Sections where we (Tech Pubs) divurge from the
information in the books.

4. Sections where we address contradictions among the
books. We do this by either stating outright that Book
A has priority over Book B and Book B has priority
over Book C, or on an individual issue-basis.

This resulted in a short style guide that I give to
contractors on their first day. Since two of the books
I chose are industry standards (Sun for style and
Gregg for grammar), contractors seem to be pretty
confident within an hour or less. Coupled with our
templates, my company gets good results with this
strategy.

Ami
In case you care, the third book is Richard Lederer's
and Richard Dowis' Sleeping Dogs Don't Lay. It's
conversational, has lots of anecdotes, and discusses
very common grammar issues in a straightforward
manner. The only reason I don't use it exclusively for
the grammar reference is that it isn't sufficiently
comprehensive, hence the Gregg.



Joy Yokley Goodreau
Linux Information Developer
LDP Collections Editor
Ofc. (512) 838-4118
T/L 678-4118
####@####.####



Previous by date: 10 Apr 2002 19:12:51 -0000 test, Joy Y Goodreau
Next by date: 10 Apr 2002 19:12:51 -0000 audience, Joy Y Goodreau
Previous in thread:
Next in thread:


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.