Elements of Style and the documentation-guide
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.
(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.)
--
Paul W. Frields, RHCE