On Tue, 2006-07-04 at 04:45 -0500, Patrick W. Barnes wrote: > As such, I have begun work on a new Fedora Documentation Style Guide. This > will become a comprehensive guide to style that will answer many questions, > including some that haven't even been asked, about the writing style that > should be used for Fedora's documentation and websites. > > http://fedoraproject.org/wiki/DocsProject/StyleGuide > > I intend to refer heavily to the Associated Press Stylebook, the Chicago > Manual of Style, the existing Documentation Guide, the GNOME Documentation > Style Guide, the style guides of a few universities and assorted other > resources. Thanks for taking this up, Patrick, I never had enough time to get it off the ground. I do have some notes around here somewhere, I think, noting some specific use cases that I kept (keep?) seeing. We may want to address them in a FAQ section if they're not sufficiently covered elsewhere. > At this time, I would be happy to accept specific suggestions for this guide. > I'll be bringing questions to this list as I get further into the writing. > There are a few style decisions that I believe we should make as a team. At > first, this document will probably reflect my own writing style very > strongly, so if anything about my writing style bothers you, now is the time > to point it out to me. ;-) Actually, you're far and away one of the better writers I've seen, judging not only from your email but also your output on the wiki. I can't think of a better individual to work on this guide. > One of the first points we might address would be the proper location of > punctuation with quotations or parenthesis. I often place periods and commas > outside of such blocks (like this), rather than inside. I find this better > suited for technical writing, since it avoids accidental inclusion of that > punctuation where it doesn't belong, but I realize that it is a bit > non-standard. When the punctuation is actually a part of the block, I do > include it inside the block, because that's "doing the right thing." > Thoughts? My understanding of accepted usage is as follows: * The rules of Standard Written English[1] apply unless inclusion of punctuation would obscure the technical content, such as shell syntax. ** SWE dictates that punctuation goes outside parentheticals, and inside quotation marks. Thus (to illustrate), sayeth the so-called "writer." ** Technical clarity requires that punctuation not be grouped with items like command syntax. For instance, you wouldn't put the full-stop in with the command "ls -la". I think that's the same thing you're saying, correct? DocBook XML makes a lot of this easier, since punctuation no longer has to be used to separate command syntax and the like from the SWE. > I was a bit torn about where to put this draft, and selected a sub-page of the > DocsProject page. It can be moved later, but I felt that this was the most > appropriate location, since this document will be targeted at the > Documentation team and not at the community as a whole. If others have > competing viewpoints, I don't have my heart set on this location. ;-) Sounds OK to me. I doubt we would ever get everyone who writes on the wiki to ingest and practice all the style guidance anyway. :-D Aha! I found my cache of style notes: http://fedoraproject.org/wiki/DocsProject/DocumentationGuide/StyleToDo Hope that helps some. = = = [1] I use the term SWE as a placeholder for "Standard Written {insert-your-language-here}." -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Project Board: http://www.fedoraproject.org/wiki/Board Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
