-
-
Notifications
You must be signed in to change notification settings - Fork 232
/
style-guide.md
134 lines (92 loc) · 6.45 KB
/
style-guide.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# Style guide
This document outlines the guidelines we use when writing documentation.
## Writing style
### Aim for clarity and brevity
> I would have written a shorter letter, but I did not have the time.
>
> — [Blaise Pascal](https://en.m.wikiquote.org/w/index.php?title=Blaise_Pascal&oldid=2978584#Quotes)
Readers' time and attention is limited.
Take the time to be extraordinarily respectful with their cognitive resources.
The same holds for communication directed to contributors and maintainers:
This is a public project, and many people will read what you write.
Use this leverage with care.
- Do: Follow the evidence-based [plain language guidelines] i.e. use simple, obvious language.
- Don't: Use jargon, many readers may not be familiar with technical terms.
- Don't: Use large words if there are smaller, simpler words that convey the same meaning.
- Do: Use the imperative voice when giving instructions.
- Example: "Add the `python310` package to `buildInputs`"
- Don't: Use a narrative voice e.g. "Now we'll add the `python310` package to `buildInputs`".
[plain language guidelines]: https://www.plainlanguage.gov/guidelines/
### Use inclusive language
Adapted from [Contributor Covenant] and [The Carpentries Code of Conduct]:
- Use welcoming and inclusive language
- Show empathy and respect towards other people
- Be respectful of different viewpoints and experiences
- Give and gracefully accept constructive criticism
- Focus on what is best for the community
Avoid idioms as they can be hard to understand for non-native English speakers.
Don't 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.
Don't use references to popular culture.
What you may consider well-known may be entirely obscure and distracting to people from different backgrounds.
[Contributor Covenant]: https://github.com/EthicalSource/contributor_covenant/blob/cd7fcf684249786b7f7d47ba49c23a6bcb3233eb/content/version/2/1/code_of_conduct.md
[The Carpentries Code of Conduct]: https://github.com/carpentries/docs.carpentries.org/blob/4691971d9f49544054410334140a4fd391a738da/topic_folders/policies/code-of-conduct.md
### Be concise
> I would have written a shorter letter, but I did not have the time.
>
> — [Blaise Pascal][Blaise Pascal]
Readers' time and attention is limited.
Take the time to be extraordinarily respectful with their cognitive resources.
The same holds for communication directed to contributors and maintainers: This is a public project, and many people will read what you write. Use this leverage with care.
[Blaise Pascal]: https://en.m.wikiquote.org/w/index.php?title=Blaise_Pascal&oldid=2978584#Quotes
### Voice
Describe the subject factually and use the imperative voice in direct instructions.
Do not assume a personal relationship with readers, prefer clarity and brevity to emotional appeal.
Use second person ("you") to refer to the reader and only use "we" to refer to the Nix Community.
### Be correct, cite sources
The only thing worse than no documentation is _incorrect documentation_.
One way to ensure correctness is by citing your sources.
If you make a claim about how something works (e.g. that a command line argument exists), link to official documentation for that subject.
We would like to maintain a network of documentation, so linking to other documentation helps to reinforce the documentation ecosystem.
It is explicitly encouraged to update or restructure the manuals where appropriate, to improve the overall experience.
## Markup and source
### Code samples
At the bare minimum code samples that are _intended_ to work should work.
If you are going to present an example that does not work (e.g. you're illustrating a common mistake) explain so beforehand.
Many readers will get stuck trying to make example code work without reading ahead to find out that the code isn't intended to work.
Code samples should all include a programming language when applicable for syntax highlighting when rendered e.g.
````
```python
print("Hello, World!")
```
````
### Headers
Reserve the largest header (`#`) for the title.
Use Markdown headers `##` through `####` to divide up content in the body of the document, but prefer to stay in the `##`-`###` range.
Finer grained headings are not necessarily better.
### One line per sentence
Write one sentence per line.
This makes review easier since the git diffs are line-oriented and the smallest level of granularity in the GitHub review interface is a line of text.
### Links
Unless explicitly required to point to the latest version of an external resource, all references should be [permanent links].
Many web services offer permalinks, such as:
- [GitHub URLs to specific commits]
- [Wikipedia URLs to specific page versions]
- [Internet Archive "Save Page Now" for persisting web pages]
Use [reference links][ref_links] to keep the source legible.
All links in a section should be grouped together at the end.
For instance:
```
## This is a section
Lorem ipsum dolor sit amet, [consectetur][adipiscing] elit. Suspendisse rutrum ligula porta, condimentum dui dignissim, imperdiet mi. Sed interdum lacus nec varius posuere. Duis auctor varius purus, ut ornare purus tempus eu. Aliquam erat volutpat. Etiam eget nunc malesuada, elementum neque eget, mollis metus. Nulla suscipit felis nec accumsan fermentum.
Integer volutpat erat sem, non varius turpis facilisis eu. Nam eu [ullamcorper][magna]. Morbi iaculis vel urna in condimentum. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus nec tellus sit amet tellus venenatis porta in et ex. Nunc sodales nisl magna, at dictum diam sollicitudin id. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec facilisis, sapien eu faucibus iaculis, nibh nibh condimentum enim, nec egestas turpis erat nec libero. Curabitur ut tincidunt odio. Praesent sed tincidunt tortor.
[adipiscing]: example.com
[magna]: example.com
```
[ref_links]: https://github.github.com/gfm/#reference-link
[permanent links]: https://en.m.wikipedia.org/wiki/Permalink
[GitHub URLs to specific commits]: https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files
[Wikipedia URLs to specific page versions]: https://en.m.wikipedia.org/wiki/Wikipedia:Linking_to_Wikipedia#Permanent_links_to_old_versions_of_pages
[Internet Archive "Save Page Now" for persisting web pages]: https://web.archive.org/save