12:31 p.m.
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
1:30 p.m.
Hi
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. :-)
I believe that public domain stuff certainly can be
included as fdl'ed content in fedora but more i think
it would be more appropriate if you do this and try to
get this into the tldp collection(discuss(a)en.tldp.org)
or somewhere more generic. It would be more useful to
many others outside fedora too
regards
Rahul Sundaram
________________________________________________________________________
Yahoo! India Matrimony: Find your partner online.
http://yahoo.shaadi.com/india-matrimony/
3:02 p.m.
On Wed, 2004-06-23 at 14:30, Rahul Sundaram wrote:
I believe that public domain stuff certainly can be
included as fdl'ed content in fedora but more i think
it would be more appropriate if you do this and try to
get this into the tldp collection(discuss(a)en.tldp.org)
or somewhere more generic. It would be more useful to
many others outside fedora too
regards
Well, I know that PD material is GPL/FDL *compatible*, but I'm not sure
to what extent that means you can cover it with the FDL without risk or
trespass. If I get it marked up as DocBook/XML, I will certainly make it
available to TLDP, although I would be surprised if there's interest
there in governing uniformity. (By the way, just to avoid confusion,
that's not a slam, nor was I referring to TLDP in my earlier comments;
I've made use of plenty of their docs in the past.)
--
Paul W. Frields, RHCE
5:17 p.m.
If I get it marked up as DocBook/XML, I
will certainly make it
available to TLDP, although I would be surprised if
there's interest
there in governing uniformity. (By the way, just to
avoid confusion,
that's not a slam, nor was I referring to TLDP in my
earlier comments;
I've made use of plenty of their docs in the past.)
Of course there is a HUGE amount of interest inside
tldp to create consistent looking documentation. as
someone who has written and reviewed docs for tldp and
generally participated in the discussion list there I
can tell you that such a document would be most
welcome
regards
Rahul Sundaram
________________________________________________________________________
Yahoo! India Matrimony: Find your partner online.
http://yahoo.shaadi.com/india-matrimony/
3:08 p.m.
At 18:31 23/06/2004, 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.
Great idea. How about asking in the commons arena,
or the fdl licence group to find out just how
to interpret that licence?
Unsure where to go, but creative commons sounds about right?
If it is OK, I'llhelp with the markup if needed.
regards DaveP
3:18 p.m.
DaveP wrote:
At 18:31 23/06/2004, 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.
Great idea. How about asking in the commons arena,
or the fdl licence group to find out just how
to interpret that licence?
You can also try <debian-legal(a)lists.debian.org>. I know there was a
huge thread on debian-devel (I think) not too long ago about some
non-freeness aspects of the FDL. In fact, IIRC, a new FDL is due any day
now that's meant to address some of these concerns. I believe it was
"due" June 1st.
HTH,
Mark
--
----------------------------------------------------------
Mark Johnson <mjohnson(a)redhat.com>
Red Hat Documentation Group <http://www.redhat.com>
Tel: 919.754.4151 Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
4:04 p.m.
On Wed, 2004-06-23 at 16:18, Mark Johnson wrote:
> Great idea. How about asking in the commons arena,
> or the fdl licence group to find out just how
> to interpret that licence?
You can also try <debian-legal(a)lists.debian.org>. I know there was a
huge thread on debian-devel (I think) not too long ago about some
non-freeness aspects of the FDL. In fact, IIRC, a new FDL is due any day
now that's meant to address some of these concerns. I believe it was
"due" June 1st.
There are definitely some legal pitfalls that are becoming apparent in
the current (soon to be "older"?) FDL. But nevertheless, I've been able
to discover thanks to your and Dave's direction that public domain docs
can be freely included in FDL docs without problems, as far as I can
tell. Public domain works are "free as the air for public use."
I would argue that you can't slap an FDL on it (and why bother anyway?),
because that puts specific restrictions on its use. However, there is no
reason it can't be distributed along with the other FDP materials,
without the FDL license and instead bearing a simple statement that it
is public domain material.
I should be able to handle the markup myself, but Dave, thanks for your
offer, and you'll be first one I'll contact if I can't complete it.
--
Paul W. Frields, RHCE
5:14 p.m.
Hi
I would argue that you can't slap an FDL on it (and
why bother anyway?),
because that puts specific restrictions on its use.
However, there is no
reason it can't be distributed along with the other
FDP materials,
without the FDL license and instead bearing a simple
statement that it
is public domain material.
afaik i know you can relicense PD stuff as FDL'ed just
like revised BSD licenses can be relicensed as GPL. PD
may not even hold as a valid distribution license
http://www.linuxmafia.com/faq/Licensing_and_Law/public-domain.html
you might want to use a liberal license like MIT
instead of public domain. I also suggest to the fedora
doc team to consider including creative commons
attribution share alike license and a new fedora legal
mailing list seems to be required
regards
Rahul Sundaram
________________________________________________________________________
Yahoo! India Matrimony: Find your partner online.
http://yahoo.shaadi.com/india-matrimony/
4:16 p.m.
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
12:49 p.m.
On Thu, 2004-06-24 at 09:35, DaveP wrote:
At 22:16 23/06/2004, Karsten Wade wrote:
>As do many organizations, we rely upon the classic "The Chicago Manual
>of Style"
Which is very US centric I'm told? Is that right Karsten?
Yes, it's the definitive guide to style for American English. However,
this is style _not_ prose, so is mainly about font size, header usage,
layout, i.e., presentation.
In looking around how others use TCMoS, it's almost like a hand-wave --
you're really saying, "We rely upon this standard of typography and
presentation." Just like the DTD called in the XML header, one is
welcome to delve further to understand everything, just as one is
welcome to accept the hand-wave and move on. After all, this is
DocBook, style is not really the point, that's taken care of in the XSL
and CSS. :) Proper tagging will be associated with a style that is, de
facto, based on TCMoS.
Okay, so how does this address Paul's question of prose style, grammar,
and so forth? Apparently, the 15th edition of TCMoS has a new section
on grammar, but I think relying upon The Elements of Style is easier and
better. Adopting TEoS as a standard for Fedora docs is a good idea.
Even if we choose not to freely distribute TEoS, we can certainly
reference it.
Here's a proposal -- let's research various online writing guides that
are public domain or covered by a license such as the FDL or Creative
Commons, allowing us to adopt and modify (fork) for our own usage. See
if we can achieve 70% of our goal the free software way. :)
- 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
1:30 p.m.
On Wed, 23 Jun 2004 13:31:11 -0400, Paul W. Frields <paul(a)frields.com> 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.
Why not point people to the original classic elsewhere on the web too?
http://www.bartleby.com/141/
2:14 p.m.
On Thu, 2004-06-24 at 14:30, Joshua Daniel Franklin wrote:
Why not point people to the original classic elsewhere on the web
too?
http://www.bartleby.com/141/
I planned to, thanks for the reminder! ;-)
--
Paul W. Frields, RHCE
2:14 p.m.
At 19:30 24/06/2004, you wrote:
Why not point people to the original classic elsewhere on the web
too?
http://www.bartleby.com/141/
Not heard of it.
Unusual though, the guy died in 46, first published in 95, then again in 99.
What happened?
.... and what makes it a 'classic' of <10 years?
I'm missing something.
regards daveP
2:30 p.m.
On Thu, 2004-06-24 at 12:14, DaveP wrote:
At 19:30 24/06/2004, you wrote:
>Why not point people to the original classic elsewhere on the web too?
>
>http://www.bartleby.com/141/
Not heard of it.
I highly recommend you pick up a copy. Knowing and using the full
Strunk and White version is, IMO, a requirement for writing good
English.
Unusual though, the guy died in 46, first published in 95, then again
in 99.
What happened?
.... and what makes it a 'classic' of <10 years?
I'm missing something.
Short version - William Strunk first started giving out his "little
book" in 1918 to his students. Strunk died in 1946. Author E.B. White,
Strunk's student in 1919, added a few opinions and revisions,
re-publishing the newly joint-authored book in 1959. It has had a few
revisions.
It is very small, easy to read and understand, and is very handy and
useful. I presume it is only the original Strunk which is in the public
domain, and that is largely the most useful part of the guide, and the
copyright not owned by a large publishing house.
More:
http://en.wikipedia.org/wiki/The_Elements_of_Style
A review:
http://www.writecraftweb.com/bookreviews/wcElementsofStyle.html
--
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
2:30 p.m.
On Thu, 2004-06-24 at 15:14, DaveP wrote:
>Why not point people to the original classic elsewhere on the web
too?
>
>http://www.bartleby.com/141/
Not heard of it.
Unusual though, the guy died in 46, first published in 95, then again in 99.
What happened?
.... and what makes it a 'classic' of <10 years?
I'm missing something.
The original 1918 version is the one that exists in the public domain.
Over the years it has been revised three times, including in 1959 by
Strunk student E. B. White (author of "Charlotte's Web," "Stuart
Little," and "The Trumpet of the Swan"). Other editions include 1972,
1979, and 2000.
http://en.wikipedia.org/wiki/The_Elements_of_Style
This was a required text for my high school English class, and I recall
clearly seeing English Composition 101 students carrying it around
during my college days.
--
Paul W. Frields, RHCE
2:36 p.m.
On Thu, 2004-06-24 at 12:30, Paul W. Frields wrote:
This was a required text for my high school English class, and I
recall
clearly seeing English Composition 101 students carrying it around
during my college days.
Heh, I often carry a battered copy around in my laptop bag, it makes for
quiet reading while waiting in line.[1] Just as with programming or
martial arts, mastery comes through repetition of the basics.
- Karsten
[1] "whilst in queue" for the idiomatic-minded :)
--
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
4:55 a.m.
On Wed, Jun 23, 2004 at 01:31:11PM -0400 or thereabouts, Paul W. Frields wrote:
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.
I have a copy of Elements of Style. I am not over-fond of it,
but that might just be because I am from the UK and thus more
used to the Oxford Guide to Style and Fowler's Modern English
Usage. Or it could be because I regularly do things of which
EoS disapproves :)
One thing that Elements of Style doesn't have, which might be
worth bearing in mind, is detail on how to write for translation.
We have a section about this in the GNOME Documentation Project
Style Guide (that title, btw, is probably a good example of how
not to write for translation: five might-be-nouns, might-be-
something-else words in a row :))
http://developer.gnome.org/documents/style-guide/locale-5.html
There are twenty topics covered there, with rules, exceptions,
bad examples and rewritten sentences. They range from some which
are good practice in any technical documentation to others which
look surprising unless you are familiar with how other languages
say things.
I believe there are sister mailing lists to this one which are
for translators. They may have other suggestions to add to that
lot. Or there may be a more well-known one. I just know about
this one because it's a Gnome one.
I assume it is likely that at least parts of the documentation
written by people on this list will end up being translated. So
if you are looking for guidelines, it might be worth bearing
these guidelines in mind too.
Telsa
8:31 a.m.
On Sun, 2004-07-04 at 05:55, Telsa Gwynne wrote:
[...snip...]
http://developer.gnome.org/documents/style-guide/locale-5.html
There are twenty topics covered there, with rules, exceptions,
bad examples and rewritten sentences. They range from some which
are good practice in any technical documentation to others which
look surprising unless you are familiar with how other languages
say things.
[...snip...]
Excellent points all, and thank you for the link. This guide mentions a
lot of ways to correct the poor style that afflicts a lot of Linux
documentation on the Web. I glanced over the GNOME guide and found
references to a number of peeves which it is designed to prevent. I
don't see an easy way of including its contents other than in whole
(which is not a problem given that it is licensed under the GFDL), but
since they're very complete in their current form that might be the most
advisable strategy. Perhaps this calls for a "part" organization in a
more comprehensive Fedora Style Guide, which might wrap up several other
guides such as the GNOME guide you mention.
I picked EoS mostly due to its copyright status in the U.S., and, I have
to admit, my personal feelings for the book. There didn't seem to be
much in it which would be odious to anyone, but certainly it's still
merely a "guide," not "law." :-)
--
Paul W. Frields, RHCE
4:29 p.m.
On Sun, 2004-07-04 at 06:31, Paul W. Frields wrote:
On Sun, 2004-07-04 at 05:55, Telsa Gwynne wrote:
[...snip...]
> http://developer.gnome.org/documents/style-guide/locale-5.html
>
> There are twenty topics covered there, with rules, exceptions,
> bad examples and rewritten sentences. They range from some which
> are good practice in any technical documentation to others which
> look surprising unless you are familiar with how other languages
> say things.
[...snip...]
Excellent points all, and thank you for the link. This guide mentions a
lot of ways to correct the poor style that afflicts a lot of Linux
documentation on the Web. I glanced over the GNOME guide and found
references to a number of peeves which it is designed to prevent. I
don't see an easy way of including its contents other than in whole
(which is not a problem given that it is licensed under the GFDL), but
since they're very complete in their current form that might be the most
advisable strategy. Perhaps this calls for a "part" organization in a
more comprehensive Fedora Style Guide, which might wrap up several other
guides such as the GNOME guide you mention.
Perhaps it should be "Fedora Documentation Style Reference Set" ... or
something similar which denotes a collection of style references that
are considered canonical or argument-ending references.
I picked EoS mostly due to its copyright status in the U.S., and, I
have
to admit, my personal feelings for the book. There didn't seem to be
much in it which would be odious to anyone, but certainly it's still
merely a "guide," not "law." :-)
Agreed. One of the important things about knowing style rules is
knowing when to break them, with intention.
- 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
7224
days inactive
7244
days old
20 comments
7 participants
participants (7)
-
Dave Pawson -
Joshua Daniel Franklin -
Karsten Wade -
Mark Johnson -
Paul W. Frields -
Rahul Sundaram -
Telsa Gwynne