-
-
Notifications
You must be signed in to change notification settings - Fork 234
/
documentation.md
296 lines (175 loc) · 12.2 KB
/
documentation.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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
# Contributing Documentation
This guide shows how you can contribute documentation to Nix, Nixpkgs, or NixOS.
It is maintained by the [Nix documentation team](https://nixos.org/community/teams/documentation), your first point of contact if you want to help out.
## List of available documentation
### Manuals
The manuals for [Nix][nix manual] ([source][nix manual src]), [Nixpkgs][nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][nixos manual] ([source][nixos manual src]) are purely reference documentation, specifying interfaces and behavior.
They also show example interactions which demonstrate how to use its components, and explain mechanisms where necessary.
The documentation team watches all pull requests to the manuals and assists contributors to get their changes merged.
You can help by doing the following:
- picking up documentation-related issues on [Nix][nix docs issues], [Nixpkgs][nixpkgs docs issues], and [NixOS][nixos docs issues].
- reviewing documentation-related pull requests on [Nix][nix docs prs], [Nixpkgs][nixpkgs docs prs], and [NixOS][nixos docs prs].
- making pull requests which improves existing documentation, such as:
- add links to definitions, commands, options, etc. where only the name is mentioned
- correct obvious errors
- clarify language
- expanding on sections that appear incomplete
- identifying sections that are not reference documentation and should be moved to nix.dev
[nix manual]: https://nixos.org/manual/nix
[nix manual src]: https://github.com/NixOS/nix/tree/master/doc/manual
[nixpkgs manual]: https://nixos.org/manual/nixpkgs
[nixpkgs manual src]: https://github.com/NixOS/nixpkgs/tree/master/doc
[nixos manual]: https://nixos.org/manual/nixos
[nixos manual src]: https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual
[nix docs issues]: https://github.com/NixOS/nix/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation
[nixpkgs docs issues]: https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%226.topic%3A+documentation%22+-label%3A%226.topic%3A+nixos%22
[nixos docs issues]: https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%226.topic%3A+documentation%22+label%3A%226.topic%3A+nixos%22+
[nix docs prs]: https://github.com/NixOS/nix/pulls?q=is%3Aopen+is%3Apr+label%3Adocumentation
[nixpkgs docs prs]: https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%226.topic%3A+documentation%22+-label%3A%226.topic%3A+nixos%22
[nixos docs prs]: https://github.com/NixOS/nixpkgs/pulls?q=is%3Aopen+is%3Apr+label%3A%226.topic%3A+documentation%22+label%3A%226.topic%3A+nixos%22+
### nix.dev
The purpose of [nix.dev] ([source][nix.dev src]) is to guide newcomers by teaching essential Nix knowledge, show best practices, and help orient users in the Nix ecosystem.
It goes into breadth, not depth.
The documentation team maintains nix.dev as editors.
You can help by doing the following:
- working on [open issues][nix.dev issues]
- reviewing [pull requests][nix.dev prs] by testing new material or features
- adding guides or tutorials following the [proposed outline](https://github.com/NixOS/nix.dev/pull/265/files)
New articles can be based on videos such as:
- [The Nix Hour] recordings
- some of the ~100 [NixCon][nixcon yt] recordings
- [Nix video guides] by @jonringer.
- [Summer of Nix 2022 talks]
Since writing a guide or tutorial is a lot of work, please make sure to coordinate with nix.dev maintainers, for example by commenting on or opening an issue to make sure it will be worthwhile.
[nix.dev]: https://nix.dev
[nix.dev src]: https://github.com/nixos/nix.dev
[nix.dev issues]: https://github.com/nixos/nix.dev/issues
[nix.dev prs]: https://github.com/nixos/nix.dev/pulls
[The Nix Hour]: https://www.youtube.com/watch?v=wwV1204mCtE&list=PLyzwHTVJlRc8yjlx4VR4LU5A5O44og9in
[nixcon yt]: https://www.youtube.com/c/NixCon
[Nix video guides]: https://www.youtube.com/user/elitespartan117j27
[Summer of Nix 2022 talks]: https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk
### nixos.org
The Nix project web site is [nixos.org] ([source][nixos website src]).
Website contents that concern learning Nix should reference or include material from nix.dev.
The [Nix marketing team] is responsible for the web site, and the documentation team assists with maintaining contents related to onboarding new users.
[nixos.org]: https://nixos.org
[nixos website src]: https://github.com/nixos/nixos-homepage
[Nix marketing team]: https://nixos.org/community/teams/marketing.html
## List of communication channels
### Matrix
Use Matrix for casual communication.
The documentation team frequents the [Nix* Documentation] room.
Old messages are extremely improbable to be read by anyone.
You can help by posting in the appropriate categories on [Discourse] what you have found valuable.
[Nix* Documentation]: https://matrix.to/#/#docs:nixos.org
[Discourse]: https://discourse.nixos.org/
### Discourse
[Discourse] is the central community hub.
This is the place for your questions, suggestions, and discussion.
The documentation team monitors the [Documentation category].
Old threads and especially posts in long threads are improbable to be read by many people.
You can help by
- asking informed questions, showing what you have done so far
- answering other people's questions
- writing down what you have learned by updating or adding a [NixOS Wiki] article, nix.dev guide or tutorial, or one of the manuals
- encouraging and helping people to incorporate their insights in the official documentation
[Documentation category]: https://discourse.nixos.org/c/dev/documentation/25
### Meetings and Events
Check the [Discourse community calendar] for real-time events.
The documentation team holds regular meetings and posts meeting notes in the [Documentation category].
You can help by joining meetings to take notes or clean them up before publishing.
[Discourse community calendar]: https://discourse.nixos.org/t/community-calendar/18589
### External sources
The Internet is full of helpful resources concerning Nix.
You can help by sharing in the [Links category] on Discourse what you have found valuable.
[Links category]: https://discourse.nixos.org/c/links/12
### Wiki
[NixOS Wiki](https://nixos.wiki/) is a collection of interlinked guides to solve common problems which are otherwise not well-documented.
It is collectively edited by the community, covers a broad range of topics.
It is only loosely organized, and does not impose quality standards.
Its purpose is to quickly and conveniently collect insights and make them readily available for everyone.
We recommend to use it as a dumping ground for more obscure Nix knowledge, and strive to make it *smaller* over time (see [NixCon 2015: Make Nix friendlier for Beginners]), by incrementally incorporating its contents into authoritative documentation and curated learning material.
The documentation team monitors changes to maintain an overview of topics of interest and prevent vandalism.
You can help with
- improving discoverability by adding categorization and relevant links
- clarifying articles and correcting errors
- removing redundant information that is already present in curated sources
- migrating information to other resources.
Where to migrate what:
- Nix interaction: [nix manual]
- Language-specific build instructions: [nixpkgs manual]
- Package, service, or hardware configuration: [nixos manual]
- Overviews, tutorials, guides, and best practices: [nix.dev]
[NixOS Wiki]: https://nixos.wiki/
[NixCon 2015: Make Nix friendlier for Beginners]: https://media.ccc.de/v/nixcon2015-3-MakeNixfriendlierforBeginners#video
## Values
### Be kind
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
[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 truthful
The only thing more confusing than no documentation is misleading documentation.
#### Use and provide evidence
Documentation should enable readers to answer all their questions on their own.
Provide links to other resources, such as the manuals, if it would help guide readers on their learning journey.
It is explicitly encouraged to update or restructure the manuals where appropriate, to improve the overall experience.
Similarly, the other information surrounding documentation should enable contributors to answer most of their questions and correct obvious errors on their own, and only then resort to opening issues.
Errors get more obvious if we can measure execution against intent.
Therefore we ask you to always make explicit the motivation behind your proposed changes.
Add references to any relevant resources in commit messages, if it helps understand the reasoning behind a significant change.
#### Ensure working code samples
Code samples must always be working correctly when run as instructed.
Nix provides us with everything needed to make this happen.
### 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
## Guidelines
### Writing style
- Follow the evidence-based [plain language guidelines].
- 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.
- Use culturally neutral language:
- Avoid idioms.
Idioms 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.
[plain language guidelines]: https://www.plainlanguage.gov/guidelines/
### 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]
[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
### Markdown
- Write one sentence per line.
This makes long sentences immediately visible, and makes it easier to manage changes.
The rule is unambiguous and does not require tooling support to be applied easily.
[Here is a discussion of different line wrapping styles.]
- Use [reference links] to keep the plain text readable.
Collect links at the end of each section, which are delimited by headings.
[Here is a discussion of different line wrapping styles.]: https://web.archive.org/web/20220519121408/https://mtsknn.fi/blog/4-1-wrapping-styles-for-markdown-prose-and-code-comments/
[reference links]: https://github.github.com/gfm/#reference-link