Fedora Documentation Style Guide

[Paul W. Frields]

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/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060704/cb5c752a/attachment.sig>