On Tuesday 04 July 2006 13:38, "Paul W. Frields" <stickster(a)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. :-)
Excellent...
--
Patrick "The N-Man" Barnes
nman64(a)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/
--