Skip to content

Commit 86954b9

Browse files
committed
CONTRIBUTING.md: refine passive voice principle
There's nothing wrong with the passive voice used correctly. Uh, "there's nothing wrong with my using the passive voice?" "There's nothing wrong with our using the passive voice?" Uh, no. ;-) Technical documentation frequently needs the passive voice because the agent is the "we" sometimes used in textbooks or tutorials consisting of the reader and the writer which is better unstated. I've changed the guideline to specify that what is discouraged is the passive voice when the active voice is equally good--namely, in cases where you'd need to use the word "by" in the passive.
1 parent f2522e2 commit 86954b9

File tree

1 file changed

+2
-1
lines changed

1 file changed

+2
-1
lines changed

CONTRIBUTING.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).
4040

4141
## General principles
4242

43-
* Please use the present tense, and [active voice](https://en.wikipedia.org/wiki/Active_voice).
43+
* Please use the present tense unless writing about history or upcoming events or planned features
44+
* Prefer [active voice](https://en.wikipedia.org/wiki/Active_voice) to the [passive voice](https://en.wikipedia.org/Passive_voice#In_English) with "by": "this is used by crafty programmers" → "crafty programmers use this"
4445
* Link to external resources (like Wikipedia) for topics that are not
4546
directly related to Perl 6 (like the math that our routines implement).
4647
* Duplicate small pieces of information rather than rely on linking.

0 commit comments

Comments
 (0)