Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
treyharris committed Jun 27, 2019
1 parent f2522e2 commit 86954b9
Showing 1 changed file with 2 additions and 1 deletion.
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Expand Up @@ -40,7 +40,8 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).

## General principles

* Please use the present tense, and [active voice](https://en.wikipedia.org/wiki/Active_voice).
* Please use the present tense unless writing about history or upcoming events or planned features
* 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"
* Link to external resources (like Wikipedia) for topics that are not
directly related to Perl 6 (like the math that our routines implement).
* Duplicate small pieces of information rather than rely on linking.
Expand Down

0 comments on commit 86954b9

Please sign in to comment.