As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions (i.e. self-editing). As I edit myself, I'm trying to make notes in my TODO for the eos-guide, which I hope will be incorporated in the eventual Style Guide. I'm hoping to do some major contribution to that guide, especially after having XML coded Strunk's book recently.
If you notice a stylistic decision that you are making consciously as you write, whether you think it is glaringly obvious or not, please feel free to send me a note about it -- off-list please, since I'll have the TODO available at my repo if you would like to look at or add to it. See http://svn.frields.org* for more information; the TODO is in the eos-guide folder.
I intend to use not just EOS, but also the GNOME Style Guidelines (which are licensed via the FDL), as source material for any work I can do on the Style Guide. If, perchance, anyone else has already started, I hope you'll consider this an offer of help. :-)
- - - - *Umm, I have mentioned that repo a few times, and I hope (Karsten, this means you especially) that *someone* will say something if my doing so is a faux pas. I am fully aware that it's not part of the FDP, nor is it intended to be. It's only a nice way for me to work on this stuff at remote locations, until the One True CVS appears, but I also wanted editors and collaborators to be able to reach it too.
On Thu, 2004-08-19 at 15:11, Paul W. Frields wrote:
As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions (i.e. self-editing). As I edit myself, I'm trying to make notes in my TODO for the eos-guide, which I hope will be incorporated in the eventual Style Guide. I'm hoping to do some major contribution to that guide, especially after having XML coded Strunk's book recently.
If you notice a stylistic decision that you are making consciously as you write, whether you think it is glaringly obvious or not, please feel free to send me a note about it -- off-list please, since I'll have the TODO available at my repo if you would like to look at or add to it. See http://svn.frields.org* for more information; the TODO is in the eos-guide folder.
I intend to use not just EOS, but also the GNOME Style Guidelines (which are licensed via the FDL), as source material for any work I can do on the Style Guide. If, perchance, anyone else has already started, I hope you'll consider this an offer of help. :-)
Awesome offer, both to get the Style Guidelines[1] started, and to collect style tips from all of us. I'll certainly send them. I'd also argue that your interest and activity so far should let you be the author/compiler of the Style Guidelines, at least initially. As much as the Doc Guide, the Style Guidelines will require group and editorial approval, so you will have to return to us for consensus on what you create more than any other doc you are likely to work on.
Once a style is set for a group, adherence to the style becomes the goblin of the editors. Changing even a small rule about punctuation can have big ramifications. We may want to consider that in terms of keeping our rules light, meaningful, and standardized.
[1] I'm trying the sound-out the idea of "Guidelines" instead of "Guide". This way we can include outside resources by reference as part of the guidelines, or just include sections of free sources like the GNOME Style Guide (not Guidelines, I think) in their entirety.
*Umm, I have mentioned that repo a few times, and I hope (Karsten, this means you especially) that *someone* will say something if my doing so is a faux pas. I am fully aware that it's not part of the FDP, nor is it intended to be. It's only a nice way for me to work on this stuff at remote locations, until the One True CVS appears, but I also wanted editors and collaborators to be able to reach it too.
I think the consensus so far is:
* We don't want outside repositories or hosted draft documents to be seen _at_all_ as official, supported, backed-up, unrootkitted, or anything sources for FDP docs or SCM (software configuration management).
* We don't specifically recommend using personal hosting, but we do mention it as an allowable part of the *writing* process (not the *publishing* process) for FDP.
In essence, what you are doing isn't much different than my hosting stuff at people.redhat.com. Personally, I should be keeping all my local work in local source control, anyway. :)
- Karsten
On Thu, 2004-08-19 at 21:34, Karsten Wade wrote:
On Thu, 2004-08-19 at 15:11, Paul W. Frields wrote:
As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions (i.e. self-editing). As I edit myself, I'm trying to make notes in my TODO for the eos-guide, which I hope will be incorporated in the eventual Style Guide. I'm hoping to do some major contribution to that guide, especially after having XML coded Strunk's book recently.
If you notice a stylistic decision that you are making consciously as you write, whether you think it is glaringly obvious or not, please feel free to send me a note about it -- off-list please, since I'll have the TODO available at my repo if you would like to look at or add to it. See http://svn.frields.org* for more information; the TODO is in the eos-guide folder.
I intend to use not just EOS, but also the GNOME Style Guidelines (which are licensed via the FDL), as source material for any work I can do on the Style Guide. If, perchance, anyone else has already started, I hope you'll consider this an offer of help. :-)
Awesome offer, both to get the Style Guidelines[1] started, and to collect style tips from all of us. I'll certainly send them. I'd also argue that your interest and activity so far should let you be the author/compiler of the Style Guidelines, at least initially. As much as the Doc Guide, the Style Guidelines will require group and editorial approval, so you will have to return to us for consensus on what you create more than any other doc you are likely to work on.
Thanks for the vote of confidence. As for passing everything back through the group, I wouldn't have it any other way! :-)
Once a style is set for a group, adherence to the style becomes the goblin of the editors. Changing even a small rule about punctuation can have big ramifications. We may want to consider that in terms of keeping our rules light, meaningful, and standardized.
[1] I'm trying the sound-out the idea of "Guidelines" instead of "Guide". This way we can include outside resources by reference as part of the guidelines, or just include sections of free sources like the GNOME Style Guide (not Guidelines, I think) in their entirety.
Right, it's GNOME Documentation Style Guide. Already showing my keen attention to detail, aren't I? ;-D
*Umm, I have mentioned that repo a few times, and I hope (Karsten, this means you especially) that *someone* will say something if my doing so is a faux pas. I am fully aware that it's not part of the FDP, nor is it intended to be. It's only a nice way for me to work on this stuff at remote locations, until the One True CVS appears, but I also wanted editors and collaborators to be able to reach it too.
I think the consensus so far is:
- We don't want outside repositories or hosted draft documents to be
seen _at_all_ as official, supported, backed-up, unrootkitted, or anything sources for FDP docs or SCM (software configuration
^^^^^ other than? (not nitpicking, just making sure I understand.)
management).
- We don't specifically recommend using personal hosting, but we do
mention it as an allowable part of the *writing* process (not the *publishing* process) for FDP.
In essence, what you are doing isn't much different than my hosting stuff at people.redhat.com. Personally, I should be keeping all my local work in local source control, anyway. :)
I think I'm on the right side of both conscience and consensus then. I'll continue to direct people to my working drafts when appropriate, with a constant notation that anything found there is a work in progress. I will make it a point to mess with the ViewCVS templates to indicate same on the site.
On Fri, 2004-08-20 at 06:07, Paul W. Frields wrote:
On Thu, 2004-08-19 at 21:34, Karsten Wade wrote:
- We don't want outside repositories or hosted draft documents to be
seen _at_all_ as official, supported, backed-up, unrootkitted, or anything sources for FDP docs or SCM (software configuration
^^^^^ other than? (not nitpicking, just making sure Iunderstand.)
management).
Bad idiomatic usage ... it should parse like, "we don't want outside repositories to be seen at all as official anything to do with FDP."
Still awkward. How about:
* Because of concerns over support, availability, redundancy, and security, we don't want non-FDP doc or source repositories to be seen as "officially" connected to the project. For example, if someone's SCM gets compromised and a rootkit trojan is loaded into document tarball ... well, bad things could happen.
Hope that is clearer,
- Karsten
Hi All,
(Probably should've started a new thread for this...)
As I'm working on the Emacs/DocBook Quickstart guide, it occurs to me that that perhaps we should provide some required sections in the beginning of the document that would be intended to address such questions as (realizing that the following are not logically independent):
- intended audience - scope of this document - what this document addresses - what this docuemt does not address - goals of this document (a pseudo re-phrasing of the above) - contributors to this document - scope of this document - [....]???
My feeling is that context that the above info provide are very important, in that they allow the reader to quickly assess the scope of the document and, hence, whether it is worth their time to read it. Past experience has shown that the mandatory inclusion of this sort of info a document/tutorial provides valuable info to the reader.
My points (and questions), are then:
- What, if any, should be the required metadata content for standard fedora docs (which at this point are tutorially structured)?
Put another way, should we require some initial sections titled, e.g.:
- intended audience
- goals of this document (N.B. these are different from the scope as described below), and also provide a basis from which readers can file bug erports. E.g. Bug pointing out how doc doesn't achieve a given goal.
- scope of this document (what it does/doesn't addressed in this section.
- contributors
'Just thinking out loud here, but honestly do feel strongly that providing a template that requires some of the above-mentioned sections would add much value to docs generated by the fedora docs project.
Since this is a rather high-level policy decision, I'm hoping to get feedback on this ASAP, as this sort of policy content would affect all docs written for fedora.
FWIW, I'm also a Debian (www.debian.org) developer and have found that clear (& existing) policies regarding the requirement of content of the type I'm advocating is greatly helpful to both authors & readers. In short, it works.
Please post your comments relating to my suggestion/proposal to the fediora-docs list. I'm interested in hearing what others think about my ideas to require initial content of this sort.
FWIW, the inclusion of this type of document metadata is used by a number of orgnaizations, so I'm not proposing anthing new here. Standard stuff, but can add great value to a document.
Thanks, Mark
On Sun, 2004-08-29 at 03:33, Mark Johnson wrote:
My points (and questions), are then:
- What, if any, should be the required metadata content for standard fedora docs (which at this point are tutorially structured)?
Suggest minimally a *info for the top level, perhaps one per separate file (delivered) which would be sect1. This to allow some record of changes with the actual document.
For any more, perhaps a better question is who want the metadata, hence what might they want? And I can't think of any 'customers' for metadata.
Put another way, should we require some initial sections titled, e.g.:
intended audience
goals of this document (N.B. these are different from the scope as described below), and also provide a basis from which readers can file bug erports. E.g. Bug pointing out how doc doesn't achieve a given goal.
Yes, but only a few lines/couple of para's; intention to stop people who are reading the wrong doc?
- scope of this document (what it does/doesn't addressed in this section.
Ditto above?
FWIW, the inclusion of this type of document metadata is used by a number of orgnaizations, so I'm not proposing anthing new here. Standard stuff, but can add great value to a document.
Our definitions of metadata are at different levels :-) Audience, goals etc I'd see as part of the document. No matter.
-
Dave Pawson -
Karsten Wade -
Mark Johnson -
Paul W. Frields