Skip to content

Commit bb72846

Browse files
committed
Reference active voice
1 parent 149a675 commit bb72846

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

CONTRIBUTING.md

+16-14
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,9 @@ cargo test
5151

5252
This project is intended to be simple to contribute to, and to always
5353
have obvious next work items available. If at any time there is not
54-
something obvious to contribute, that is a bug. Please ask for
55-
assistance on the [libz blitz] thread, or email Brian Anderson
56-
directly ([email protected]).
54+
something obvious to contribute, that is a bug. Feel free to ask for
55+
additional support at the
56+
[Rust Ecosystem Working Group](https://gitter.im/rust-lang/WG-ecosystem).
5757

5858
The development process for the cookbook is presently oriented around
5959
crates: we decide which crates to represent in the cookbook, then come
@@ -146,16 +146,18 @@ something a typical Rust user typically wants to do.
146146
#### Description
147147

148148
Describe traits imported and the methods used. Think about what information
149-
supports the use case and might not be obvious to someone new. Keep the
150-
description to 1-4 sentences, avoiding explanations outside the scope of the
149+
supports the use case and might not be obvious to someone new. Keep the
150+
description to 1-4 sentences, avoiding explanations outside the scope of the
151151
code sample.
152152

153-
Use third person narative of the code execution, taking the opportunity
154-
to link to API documentation. Hyperlink all references to APIs, either
153+
Use third person narrative of the code execution, taking the opportunity
154+
to link to API documentation. Always use
155+
[active voice](https://www.plainlanguage.gov/guidelines/conversational/use-active-voice/).
156+
Hyperlink all references to APIs, either
155157
on doc.rust-lang.org/std or docs.rs, and style them as `code`. Use
156158
wildcard version specifiers for crate links.
157159

158-
Any requirements to execute the code that are not apparent, such as
160+
Any requirements to execute the code that are not apparent, such as
159161
passing environment flags, or configuring `Cargo.toml` should be added
160162
after the code sample.
161163

@@ -164,8 +166,8 @@ after the code sample.
164166
> distribution, then sample from that distribution using
165167
> [`Distribution::sample`] with help of a random-number
166168
> generator [`rand::Rng`].
167-
>
168-
> The [distributions available are documented here][rand-distributions].
169+
>
170+
> The [distributions available are documented here][rand-distributions].
169171
> An example using the [`Normal`] distribution is shown below.
170172
171173
[uniform distribution]: https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)
@@ -190,11 +192,11 @@ error handling correctly and propagate errors with `?` (not `try!`, `urwrap`, or
190192
`expect`). If there is no need for error handling in the example, prefer `main()`.
191193

192194
Avoid glob imports (`*`), even for preludes, so that users can see what
193-
traits are called. (Some crates might consider using glob imports for preludes
195+
traits are called. (Some crates might consider using glob imports for preludes
194196
best practice, making this awkward.)
195197

196198
Examples should be simple and obvious enough that an experienced dev
197-
do not need comments.
199+
do not need comments.
198200

199201
Examples should compile without warnings, clippy lint warnings, or panics.
200202
The code should be formatted by rustfmt. Hide all error boilerplate and
@@ -206,9 +208,9 @@ explanation in the description.
206208

207209
> ```rust
208210
> extern crate rand;
209-
>
211+
>
210212
> use rand::distributions::{Normal, Distribution};
211-
>
213+
>
212214
> fn main() {
213215
> let mut rng = rand::thread_rng();
214216
> let normal = Normal::new(2.0, 3.0);

0 commit comments

Comments
 (0)