On Tuesday 04 July 2006 13:38, "Paul W. Frields" <stickster@xxxxxxxxx> 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@xxxxxxxxx http://www.n-man.com/ LinkedIn: http://www.linkedin.com/in/nman64 Have I been helpful? Rate my assistance! http://rate.affero.net/nman64/ --
Attachment:
pgp0ZhD57M1BO.pgp
Description: PGP signature
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
