Clarifying some language standards for the docs #3149
Conversation
| .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code | ||
| .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html | ||
| .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma |
There was a problem hiding this comment.
you're an OSS animal, you should now that you should always add a linefeed character at the end of a document 😉
There was a problem hiding this comment.
you just coined a fine term OSS animal 👶
|
btw, you keep forgetting the PR template... |
|
Hey guys! I've just made a few small updates. The only thing really to decide is the capitalization rule. Thanks! |
|
👍 for the current capitalization rule proposal |
| Language Standards | ||
| ------------------ | ||
|
|
||
| * For sections, use the following rule for capitalization: |
There was a problem hiding this comment.
I think this is actually right. For example, if you google for "for sections use a", there are some mixed results, but the first is from a writing guide that uses the comma :).
There was a problem hiding this comment.
@weaverryan, did you download the guide and read it in context? It has a paragraph as a context and a previous sentence which has a line plot. So punctuation there make sense since it is a sequel. However this on line 109, in our case, proves to be a misuse for exactly the same reasons, it has no context as it is the first sentence on the paragraph and thereby should not have been used.
In the programmer world there is an abuse of commas; we all know this. I hope this critical thing could be reverted 👶
a la @pboreli and a la @wouterj
this time I think i got your back @weaverryan 👶
There was a problem hiding this comment.
I checked into this with a book editor I know and got a really fantastic response :)
You have an interesting situation here. "For sections" is a prepositional phrase consisting of the preposition "for" and the noun "sections." When a prepositional phrase is used at the beginning of a sentence, it's considered an introductory modifier, which generally signals the need for a comma. Some style guides say that prepositional phrases of four words or less do not require a comma, although I think it's always helpful to clarify the sentence.
A good way to check if you have a prepositional phrase is to see if you can write the same sentence without a comma by putting the phrases in a different order. "Around dinner time, the cows come home," can also be written as "The cows come home around dinner time." (I have no idea why that's the first prepositional phrase that popped into my head...)
Anyway, in your case, rewriting the sentence would result in: "Use the following rule for capitalization for sections." This sounds a little awkward, which may be why you got called out on it. Removing the other "for" would help. You could say, "For sections, use the following capitalization rules," or "Use the following capitalization rules for sections."
So, it looks like the comma can be there, and adding it can help clarity. But, as she points out in the last paragraph, this can be phrased better. I've updated it at sha: a448eac with the nicer wording.
Thanks!
There was a problem hiding this comment.
you got the contacts man, nice!
you got my back now thanks
👶
There was a problem hiding this comment.
hehe, great discussion! Never expected the doc guys to be so strict 🚓
There was a problem hiding this comment.
It was a fun one to ask about - I couldn't think of any reason why I thought I was right... so we had to find an expert!
There was a problem hiding this comment.
Now I'm feeling very comfortable here with my fussy consistency spleen, thanks.
Clarifying some language standards for the docs
Hi everyone!
In a conversation on #3131, we thought it might be helpful to add a few language-related standards. These standards here outline basically what we've done on the past, though we're certainly inconsistent in a few places with the titles at least.
Thanks!