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

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Clarifying some language standards for the docs
  • Loading branch information
@weaverryan
weaverryan committed Nov 9, 2013
commit c3816f8280f86bbb37a4086e330a623de3e94f27
10 changes: 9 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,14 @@ 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
------------------

* Capitalize the first letter of any heading and the first letter of all
nouns and adjectives afterwards (verbs are lowercase);
Copy link
Member

Choose a reason for hiding this comment

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

I suggest to follow some of the overall Title case standards. I think I like "Capitalization of the first word, and all other words, except for articles, prepositions, and conjunctions" the most.

Copy link
Member

Choose a reason for hiding this comment

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

👍 I second that.

Copy link
Member Author

Choose a reason for hiding this comment

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

This seems like a good idea. But Capitalization of the first word, and all other words, except for closed-class words is closer to what we have now - I think we should use that.

Copy link
Member

Choose a reason for hiding this comment

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

tbh, I don't care which rule is token. The only thing I want to is to make all headlines follow that rule. If it requires me less work on making it consistent, I'm +1 for your proposal.

Copy link
Contributor

Choose a reason for hiding this comment

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

If you want to revise the docs and make all existing headings follow that rule, we could share the work. Please let me know if you need support.

* Do not use `Serial (Oxford) Commas`_;
* You should use a form of *you* instead of *we*.
Copy link
Member

Choose a reason for hiding this comment

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

What about changing this to: "Use the second person"

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 we should have both - your's is more proper, what we have now is a more easily understood example :)


.. _`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
Copy link
Member

Choose a reason for hiding this comment

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

you're an OSS animal, you should now that you should always add a linefeed character at the end of a document 😉

Copy link
Contributor

Choose a reason for hiding this comment

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

you just coined a fine term OSS animal 👶