diff options
Diffstat (limited to 'guides/source/api_documentation_guidelines.md')
| -rw-r--r-- | guides/source/api_documentation_guidelines.md | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index d403de5fd3..311cc23cf0 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -42,6 +42,28 @@ Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERB. Wh Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database". +Prefer wordings that avoid "you"s and "your"s. For example, instead of + +```markdown +If you need to use `return` statements in your callbacks, it is recommended that you explicitly define them as methods. +``` + +use this style: + +```markdown +If `return` is needed it is recommended to explicitly define a method. +``` + +That said, when using pronouns in reference to a hypothetical person, such as "a +user with a session cookie", gender neutral pronouns (they/their/them) should be +used. Instead of: + +* he or she... use they. +* him or her... use them. +* his or her... use their. +* his or hers... use theirs. +* himself or herself... use themselves. + English ------- |