2022-07-11 09:48:50 -04:00
|
|
|
# Contributing to nix.dev
|
|
|
|
|
|
|
|
|
|
## Guides
|
|
|
|
|
|
|
|
|
|
### Writing style
|
|
|
|
|
|
|
|
|
|
Describe the subject factually.
|
|
|
|
|
Use imperative in direct instructions.
|
|
|
|
|
|
|
|
|
|
Clarity and brevity outweighs emotional appeal.
|
|
|
|
|
Do not presuppose a personal relationship with readers.
|
|
|
|
|
|
|
|
|
|
Address the reader with "you" when necessary.
|
|
|
|
|
Clarify identity if you use "we".
|
|
|
|
|
Generally, "we" are the Nix community and, more specifically, nix.dev authors.
|
|
|
|
|
|
2022-07-28 19:21:59 -04:00
|
|
|
Use culturally neutral language:
|
|
|
|
|
|
|
|
|
|
- Avoid idioms.
|
|
|
|
|
|
|
|
|
|
Idioms can be hard to understand for non-native English speakers.
|
|
|
|
|
|
|
|
|
|
- Do not try to be funny.
|
|
|
|
|
|
|
|
|
|
Humor is highly culturally sensitive.
|
|
|
|
|
At best, jokes may obfuscate the relevant instructions.
|
|
|
|
|
At worst, jokes may offend readers and invalidate our effort to help them learn.
|
|
|
|
|
|
|
|
|
|
- Do not use references to popular culture.
|
|
|
|
|
|
|
|
|
|
What you may consider well-known may be entirely obscure and distracting to people from different backgrounds.
|
|
|
|
|
|
