diff options
author | Junio C Hamano <gitster@pobox.com> | 2021-07-15 09:25:27 -0700 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2021-07-16 11:35:46 -0700 |
commit | 5b1cd37e4439edaabf781a1c840f5af4c003e727 (patch) | |
tree | 038d1662a320212691947dc3a82fb003a38dc61d /contrib/subtree/git-subtree.txt | |
parent | *: fix typos (diff) | |
download | tgif-5b1cd37e4439edaabf781a1c840f5af4c003e727.tar.xz |
CodingGuidelines: recommend gender-neutral description
Technical writing seeks to convey information with minimal
friction. One way that a reader can experience friction is if they
encounter a description of "a user" that is later simplified using a
gendered pronoun. If the reader does not consider that pronoun to
apply to them, then they can experience cognitive dissonance that
removes focus from the information.
Give some basic tips to guide us avoid unnecessary uses of gendered
description.
Using a gendered pronoun is appropriate when referring to a specific
person.
There are acceptable existing uses of gendered pronouns within the
Git codebase, such as:
* References to real people (e.g. Linus Torvalds, "the Git maintainer").
Do not misgender real people. If there is any doubt to the gender of a
person, then avoid using pronouns.
* References to fictional people with clear genders (e.g. Alice and
Bob).
* Sample text used in test cases (e.g t3702, t6432).
* The official text of the GPL license contains uses of "he or she",
but using singular "they" (or modifying the text in some other
way) is not within the scope of the Git project.
* Literal email messages in Documentation/howto/ should not be edited
for grammatical concerns such as this, unless we update the entire
document to fit the standard documentation format. If such an effort is
taken on, then the authorship would change and no longer refer to the
exact mail message.
* External projects consumed in contrib/ should not deviate solely for
style reasons. Recommended edits should be contributed to those
projects directly.
Other cases within the Git project were cleaned up by the previous
changes.
Co-authored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'contrib/subtree/git-subtree.txt')
0 files changed, 0 insertions, 0 deletions