summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2021-07-28 20:18:02 (GMT)
committerJunio C Hamano <gitster@pobox.com>2021-07-28 20:18:02 (GMT)
commit546adc4950185464c75158301c854b0f55dcf465 (patch)
treee18223afbfefcd7e207c37353eb989d68bca0ea1 /Documentation/CodingGuidelines
parentb271a3034fc54a7c84ae5803d72f14a29b172c78 (diff)
parent5b1cd37e4439edaabf781a1c840f5af4c003e727 (diff)
downloadgit-546adc4950185464c75158301c854b0f55dcf465.zip
git-546adc4950185464c75158301c854b0f55dcf465.tar.gz
git-546adc4950185464c75158301c854b0f55dcf465.tar.bz2
Merge branch 'ds/gender-neutral-doc-guidelines'
A guideline for gender neutral documentation has been added. * ds/gender-neutral-doc-guidelines: CodingGuidelines: recommend gender-neutral description
Diffstat (limited to 'Documentation/CodingGuidelines')
-rw-r--r--Documentation/CodingGuidelines45
1 files changed, 45 insertions, 0 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089..711cb91 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -551,6 +551,51 @@ Writing Documentation:
documentation, please see the documentation-related advice in the
Documentation/SubmittingPatches file).
+ In order to ensure the documentation is inclusive, avoid assuming
+ that an unspecified example person is male or female, and think
+ twice before using "he", "him", "she", or "her". Here are some
+ tips to avoid use of gendered pronouns:
+
+ - Prefer succinctness and matter-of-factly describing functionality
+ in the abstract. E.g.
+
+ --short:: Emit output in the short-format.
+
+ and avoid something like these overly verbose alternatives:
+
+ --short:: Use this to emit output in the short-format.
+ --short:: You can use this to get output in the short-format.
+ --short:: A user who prefers shorter output could....
+ --short:: Should a person and/or program want shorter output, he
+ she/they/it can...
+
+ This practice often eliminates the need to involve human actors in
+ your description, but it is a good practice regardless of the
+ avoidance of gendered pronouns.
+
+ - When it becomes awkward to stick to this style, prefer "you" when
+ addressing the the hypothetical user, and possibly "we" when
+ discussing how the program might react to the user. E.g.
+
+ You can use this option instead of --xyz, but we might remove
+ support for it in future versions.
+
+ while keeping in mind that you can probably be less verbose, e.g.
+
+ Use this instead of --xyz. This option might be removed in future
+ versions.
+
+ - If you still need to refer to an example person that is
+ third-person singular, you may resort to "singular they" to avoid
+ "he/she/him/her", e.g.
+
+ A contributor asks their upstream to pull from them.
+
+ Note that this sounds ungrammatical and unnatural to those who
+ learned that "they" is only used for third-person plural, e.g.
+ those who learn English as a second language in some parts of the
+ world.
+
Every user-visible change should be reflected in the documentation.
The same general rule as for code applies -- imitate the existing
conventions.