diff options
Diffstat (limited to 'doc/documentation/chapters/contributing.texi')
-rw-r--r-- | doc/documentation/chapters/contributing.texi | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/documentation/chapters/contributing.texi b/doc/documentation/chapters/contributing.texi index a2b21df4c..c077ea3f3 100644 --- a/doc/documentation/chapters/contributing.texi +++ b/doc/documentation/chapters/contributing.texi | |||
@@ -53,3 +53,47 @@ in the respective authors file or section, please do let us know. | |||
53 | @node Contributing to the Reference Manual | 53 | @node Contributing to the Reference Manual |
54 | @section Contributing to the Reference Manual | 54 | @section Contributing to the Reference Manual |
55 | 55 | ||
56 | @itemize @bullet | ||
57 | |||
58 | @item When writing documentation, please use | ||
59 | @uref{https://en.wikipedia.org/wiki/Singular_they, gender-neutral wording} | ||
60 | when referring to people, such as singular “they”, “their”, “them”, and so | ||
61 | forth. | ||
62 | |||
63 | @item Keep line length below 74 characters, except for URLs. | ||
64 | URLs break in the PDF output when they contain linebreaks. | ||
65 | |||
66 | @item Do not use tab characters (see chapter 2.1 texinfo manual) | ||
67 | |||
68 | @item Use neutral language and third person perspective in the text | ||
69 | |||
70 | @item So, when you refer to a user in general or addressing the user, | ||
71 | refer to (1). | ||
72 | @itemize @bullet | ||
73 | @item Unsolved exceptions for canonical reasons: When refering to Alice, | ||
74 | use "she". When refering to Bob, use "he". These are long established | ||
75 | examples and they should either be replaced (avoid Alice and Bob | ||
76 | examples when you can) or followed. | ||
77 | @end itemize | ||
78 | |||
79 | @item Use 2 spaces between sentences, so instead of: | ||
80 | |||
81 | @example | ||
82 | We do this and the other thing. This is done by foo. | ||
83 | @end example | ||
84 | |||
85 | Write: | ||
86 | |||
87 | @example | ||
88 | We do this and the other thing. This is done by foo. | ||
89 | @end example | ||
90 | |||
91 | @item Use @@footnote@{@} instead of putting an @@*ref@{@} to the | ||
92 | footnote on a collected footnote-page. | ||
93 | In a 200+ pages handbook it's better to have footnotes accessible | ||
94 | without having to skip over to the end. | ||
95 | |||
96 | @item Avoid unnecessary footnotes, keep the text self-explanatory and | ||
97 | in a simple language where possible/necessary. | ||
98 | |||
99 | @end itemize | ||