Elements of Style and the documentation-guide

[Karsten Wade]

Paul - your post stirs up several good ideas.  Just a few thoughts right
now, more to come when they are worth sharing ...

On Wed, 2004-06-23 at 10:31, Paul W. Frields wrote:
> After spending the last several days doing markup on a syntactically and
> grammatically, er, "challenged" tutorial, I found myself in need of the
> solace of Strunk and White's "The Elements of Style," if only to remind
> myself that good writing does indeed exist outside my imagination. I
> noticed during my Web search that EoS was released some years ago into
> the public domain, and can be found in a variety of formats, although
> DocBook XML was not one of these as far as I can tell.
> 
> I realize that "public domain" != "FDL," and therefore am wondering if
> anyone out there has sufficient expertise to address the extent to which
> EoS might be included in the documentation-guide. It would be a handy
> reference for contributors, so they might acquaint themselves with the
> way to write concisely before beginning a tutorial from scratch. It also
> would help editors (myself included) to make the right changes when
> presented with documentation that has been tortured and abused before a
> handoff. :-)
> 
> In addition, or as an alternative, to EoS, perhaps there should be some
> guidelines that have been useful to the Red Hat staff in preparing their
> official RHL and RHEL documentation over the years. I have found those
> guides consistently clear, concise, and informative, and I would hope
> that FDP products would be of similar quality. By comparison, a lot of
> the documentation on the Web is poorly written, and often lapses into
> informalities, colloquialism, unhelpful jargon, and vague generalities.
> On the other hand, in many cases those materials will form the basis for
> future FDP work, so FDP content guidelines might be very useful as time
> goes on.

As do many organizations, we rely upon the classic "The Chicago Manual
of Style"
(http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/about.html) as an
underpinning for our editorial style.  There are other layers we've
added on top of that, and off the top of my head, I don't know if they
would be useful or relevant to Fedora docs, or even available at all.

But having that book in your bookshelf couldn't hurt, new fifteenth
edition now available!  But, yeah, we can't put it in an RPM to include
in the docs authoring section of comps.xml ...

I haven't found a free-licensed equivalent of the Chicago Manual of
Style.  What I've seen are focused on specific niches, such as travel
writing[1] or Wiki[2] writing.  If we find a style guide that someone
has done already, and it's licensed correctly, we could adopt, absorb,
or fork it as our own.

I have seen guides that are based on The Chicago M.O.S.[3], and I don't
know how they handle their legality.

Consistency is the key, more so than one person's idea of "better"
compared to another's. 

[1]
http://wikitravel.org/en/article/Wikitravel:Manual_of_style
http://www.world66.com/about/contributing_contents/manual_of_style

[2]
http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style

[3]
http://www.lib.ohio-state.edu/guides/chicagogd.html

> (In the event that EoS can be included in the documentation-guide, I
> will volunteer to do markup, since I brought up the issue. I doubt it
> will be very difficult in any case, given that it's dominated by
> non-technical matter.)

Looks like there is no fedora-legal-list, so I wouldn't know where to
take that question ... I'll ask around, see if any answers present
themselves.

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
this .signature subject to random changes
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41