Fedora Documentation Style Guide

[Patrick W. Barnes]

On Tuesday 04 July 2006 13:38, "Paul W. Frields" <stickster at gmail.com> wrote:
>
> 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.

If they're issues that you've really noticed on a regular basis, they'll 
probably get more coverage than just a FAQ item.  ;-)

>
> > 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.

Thank you, kind sir.  Still, writing styles vary greatly, and that's not to 
say that any are right or wrong, but I would love to hear suggestions from 
those who might use writing styles that are different from my own.

>
> > 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.

Agreed on all points.

>
> > 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

At least it will still be available to anyone who cares.  :-)

>
> Aha! I found my cache of style notes:
>
> http://fedoraproject.org/wiki/DocsProject/DocumentationGuide/StyleToDo
>
> Hope that helps some.

Excellent...

-- 
Patrick "The N-Man" Barnes
nman64 at n-man.com

http://www.n-man.com/

LinkedIn:
http://www.linkedin.com/in/nman64

Have I been helpful?  Rate my assistance!
http://rate.affero.net/nman64/
-- 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060705/acb2d381/attachment.sig>