Skip to content

Clarifying some language standards for the docs #3149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 16, 2013
Merged

Clarifying some language standards for the docs #3149

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c3816f8
Clarifying some language standards for the docs
weaverryan Nov 3, 2013
ec0981d
[#3149] Tweaks thanks to @WouterJ
weaverryan Nov 9, 2013
40241af
[#3149] Tweaking language to use a standard for capitalization
weaverryan Nov 9, 2013
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion contributing/documentation/standards.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ Sphinx
shorthand);
* Inline hyperlinks are **not** used. Separate the link and their target
definition, which you add on the bottom of the page;
* You should use a form of *you* instead of *we*.

Example
~~~~~~~
Expand Down Expand Up @@ -104,5 +103,17 @@ Example
In Yaml you should put a space after ``{`` and before ``}`` (e.g. ``{ _controller: ... }``),
but this should not be done in Twig (e.g. ``{'hello' : 'value'}``).

Language Standards
------------------

* For sections, use the following rule for capitalization:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove comma
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 👶
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you got the contacts man, nice!
you got my back now thanks

👶
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hehe, great discussion! Never expected the doc guys to be so strict 🚓
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now I'm feeling very comfortable here with my fussy consistency spleen, thanks.
`Capitalization of the first word, and all other words, except for closed-class words`_:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capitalize the ...?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also you say not to use serial comma and so shouldn't this commas also be removed before the and?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you're right, but I'm quoting some exact text on that page.
The Vitamins are in my Fresh California Raisins
* Do not use `Serial (Oxford) Commas`_;
* You should use a form of *you* instead of *we* (i.e. avoid the first person
point of view: use the second instead).

.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
.. _`Capitalization of the first word, and all other words, except for closed-class words`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles
.. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma