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.)
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@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/
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@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.)
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/
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
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@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
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@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.
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/
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
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
On Wed, 23 Jun 2004 13:31:11 -0400, Paul W. Frields paul@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?
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?
I planned to, thanks for the reminder! ;-)
At 19:30 24/06/2004, you wrote:
Why not point people to the original classic elsewhere on the web too?
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
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?
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
On Thu, 2004-06-24 at 15:14, DaveP wrote:
Why not point people to the original classic elsewhere on the web too?
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.
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 :)
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
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." :-)
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
-
Dave Pawson -
Joshua Daniel Franklin -
Karsten Wade -
Mark Johnson -
Paul W. Frields -
Rahul Sundaram -
Telsa Gwynne