From a176bd095c3cba498369870681695bb29a68f0f9 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Thu, 12 Dec 2013 21:48:33 +0100 Subject: docs guidelines: recommends wording in a way that avoids "you"s and "your"s --- guides/source/api_documentation_guidelines.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'guides') diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index ccb51ce73c..31ef18d21e 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -42,7 +42,21 @@ 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". -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: +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. -- cgit v1.2.3