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/