In reply to @9999years:matrix.org
e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv

In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong

In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix

In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix

In reply to @infinisil:matrix.org
Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132

In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong

In reply to @9999years:matrix.org
i've heard this one before ... every time someone explains that they've been driven out of the nix community due to perceived hostility there's a lot of "we're here to listen and learn" but nothing ever seems to change

(and also, Qyriad)

I would have preferred it if you read my response with no hostility, because there frankly wasn't any. There was however, a degree of frustration as I thought your messages were quite hostile, and I struggled to respond cogently to them on my first try (I did not want to produce a wall-of-text, something I fall into easily).

As for why I thought your comments were hostile: they seemed entirely out of the blue. I scrolled up to try and find the context but could not find any; if I missed it please link me to it. Anyway, given this lack of context: I was not sure what these messages communicate apart from insinuating that those working on the docs think the docs are close to being done and/or that they aren't working hard enough? Rather hostile, yes?

So take my "no." for what it was, if you can (though I appreciate that this is likely not possible given how the situation evolved): a note of disagreement. Frustrated disagreement yes, but not hostile disagreement. Certainly no more hostile than your own message.

As for why I disagree: well, I am still not clear if you want to know. I am also not clear on how to not make it a wall of text. I am going to risk trying to put together something regardless. I hope again (though I appreciate that this is likely not possible) that you'll put some effort into reading what I'm sharing, instead of dismissing it outright as a "wall of text".

I decided to start contributing to Nix docs a few weeks ago, by doing light review work. I also really wanted to contribute to a working Wiki, and therefore was interested in getting Wiki 2.0 rolling. On the PR review front, infinisil's PR on File Sets grabbed my attention. I could not understand their answer, and found it frustrating, which lead me to put down this wall-of-text.

I am glad that proofconstruction wrote me a fairly detailed response, and I appreciate that they put in some effort to take me sincerely, even though it was hard and their frustration bled through. They made their doubt of my sincerity clear, and I made my own unhappiness with their doubt clear. Regardless, we gave each other the space to speak, and reached a mutual understanding, as you can see.

Far more important however, is what proofconstruction shares. Please read that, even if you cannot summon the motivation to read what I wrote. I learned a lot from it. And it's an excellent introduction to what the actual issues are:

1. Lack of humanpower, and lack of resources to ask people to work on a non-volunteer basis.

2. Split of community, and therefore the above mentioned resources, due to flakes, and how flakes are being conveyed/pushed.

3. Noise in the communication "channel": there is a lot* of misleading and/or poor quality content around Nix. Part of this may be put down to the way search engines work today, part due to how people are pushed to advertise themselves with blog posts, or where current trends in fashion are. Part of it is also due to the tragedy of the wiki which people are working hard to revive.

But barring all that, a non-trivial part of it is also due to politics. Nix is being advertised in ways that are unfair to those doing the actual work in the trenches.

Frankly, the learning journey becomes much easier if a beginner (speaking also as a fellow beginner!):

• drops home-manager: home-manager is not great for a variety of reasons, but a crucial one is that it uses concepts and terminology that are superficially similar to NixOS, but only superficially. This forces a beginner to have to learn two models, even though they think they are learning one model, and its frustrating when that knowledge isn't cross-applicable.
• drops flakes, flake-utils, etc. (and were instead exposed to niv or npins)

Later, once you're more familiar with Nix, you can go back to playing with those (if you still feel the need). But already, by implementing the aboeve two points, the documentation situation for a beginner has improved by cutting down on what they are required to take in at one go.

1. In order to document something, it is also necessary that the thing in question is documentable. Nix is in such a position (due to lack of resources, and humanpower, but also choices on the part of leadership) that it is not easy to document for fairly simple reasons such as: lack of typing. Type systems (amongst other things) are very helpful for auto-generation of documentation, and having "self-documenting" code (e.g. sometimes a function signature can tell you a lot about what a function is doing!).

So, as a consequence of this: should people work doing painful, manual work that might quickly go out of date? Or should they work on getting some of the basic infrastructure that would help with this in place?

1. Nix's documentation is clearly not great. However, I do not think it's bad, having actually stuck with using it. Can some of it be hard to read? Certainly, but 4 times out of 5 (roughly, guesstimating), it gets the point across, which is okay for documentation.

To be productive (relatively speaking), I had to follow a sequence like this:

• learn how to bookmark search engines so that I can query directly from my URL bar (https://support.mozilla.org/en-US/questions/1284520) (this isn't well documented for a lot of browsers either)
• bookmark Nixpkgs manual, NixOS manual, Nix Reference Manual (search engine bookmarkable), Nix.dev (in order to make up for the fact that there is no central repo
• bookmark (as search engines) search.nixos.org/packages? and search.nixos.org/options?
• bookmark (as search engines) GitHub queries lang:nix org:nixos <...> and lang:sh org:nixos <...> and finally (lang:nix) AND NOT ("home" OR "home-manager" <...>) -- because yes, reading the source code is unavoidable. But it's doable. It's okay. And more often than not, you'll be surprised by how well documented it is (which also should lead one to wonder: why is it hard to automate sharing of documentation between primary nix docs and the source code? see point 4 above)

That's enough to cover 80% of my needs. The remainder: I have to ask others for pointers about, and/or searching for PRs in flight for nix docs, and/or I have just discovered something undocumented.

Still though, this is 4/5. Not great, but not terrible.

As an illustration of the "noise in the channel" issue are you aware of:

• nix.dev? If so, when did you become aware of it? Was it one of the earliest/first resources you became familiar with? (For me, it was most certainly not, although today I see that it is linked under "first steps with Nix"...)

• Are you familiar with high-level conceptual articles like Taming Unix With Nix? If not, why not? Why don't they show up much, much higher on search engines? Why aren't they thrown around freely on HN?

• Are you familiar with the fact that the "Unofficial NixOS Wiki" is not well maintained, and contains lots of extremely low quality information?

• Are you familiar with the fact that the Nix Pills are currently not in a great shape, especially for beginners, despite them being advertised on nixos.org's learn page?

In reply to @9999years:matrix.org
i've heard this one before ... every time someone explains that they've been driven out of the nix community due to perceived hostility there's a lot of "we're here to listen and learn" but nothing ever seems to change

(and also, Qyriad)

I would have preferred it if you read my response with no hostility, because there frankly wasn't any. There was however, a degree of frustration as I thought your messages were quite hostile, and I struggled to respond cogently to them on my first try (I did not want to produce a wall-of-text, something I fall into easily).

As for why I thought your comments were hostile: they seemed entirely out of the blue. I scrolled up to try and find the context but could not find any; if I missed it please link me to it. Anyway, given this lack of context: I was not sure what these messages communicate apart from insinuating that those working on the docs think the docs are close to being done and/or that they aren't working hard enough? Rather hostile, yes?

So take my "no." for what it was, if you can (though I appreciate that this is likely not possible given how the situation evolved): a note of disagreement. Frustrated disagreement yes, but not hostile disagreement. Certainly no more hostile than your own message.

As for why I disagree: well, I am still not clear if you want to know. I am also not clear on how to not make it a wall of text. I am going to risk trying to put together something regardless. I hope again (though I appreciate that this is likely not possible) that you'll put some effort into reading what I'm sharing, instead of dismissing it outright as a "wall of text".

I decided to start contributing to Nix docs a few weeks ago, by doing light review work. I also really wanted to contribute to a working Wiki, and therefore was interested in getting Wiki 2.0 rolling. On the PR review front, infinisil's PR on File Sets grabbed my attention. I could not understand their answer, and found it frustrating, which lead me to put down this wall-of-text.

I am glad that proofconstruction wrote me a very detailed response, and I appreciate that they put in some effort to take me sincerely, even though it was hard and their frustration bled through. They made their doubt of my sincerity clear, and I made my own unhappiness with their doubt clear. Regardless, we gave each other the space to speak, and reached a mutual understanding, as you can see.

Far more important however, is what proofconstruction shares. Please read that, even if you cannot summon the motivation to read what I wrote. I learned a lot from it. And it's an excellent introduction to what the actual issues are:

1. Lack of humanpower, and lack of resources to ask people to work on a non-volunteer basis.
2. Split of community, and therefore the above mentioned resources, due to flakes, and how flakes are being conveyed/pushed.
3. Noise in the communication "channel": there is a lot* of misleading and/or poor quality content around Nix. Part of this may be put down to the way search engines work today, part due to how people are pushed to advertise themselves with blog posts, or where current trends in fashion are. Part of it is also due to the tragedy of the wiki which people are working hard to revive.

But barring all that, a non-trivial part of it is also due to politics. Nix is being advertised in ways that are unfair to those doing the actual work in the trenches.

Frankly, the learning journey becomes much easier if a beginner (speaking also as a fellow beginner!):

• drops home-manager: home-manager is not great for a variety of reasons, but a crucial one is that it uses concepts and terminology that are superficially similar to NixOS, but only superficially. This forces a beginner to have to learn two models, even though they think they are learning one model, and its frustrating when that knowledge isn't cross-applicable.
• drops flakes, flake-utils, etc. (and were instead exposed to niv or npins)

Later, once you're more familiar with Nix, you can go back to playing with those (if you still feel the need). But already, by implementing the aboeve two points, the documentation situation for a beginner has improved by cutting down on what they are required to take in at one go.

1. In order to document something, it is also necessary that the thing in question is documentable. Nix is in such a position (due to lack of resources, and humanpower, but also choices on the part of leadership) that it is not easy to document for fairly simple reasons such as: lack of typing. Type systems (amongst other things) are very helpful for auto-generation of documentation, and having "self-documenting" code (e.g. sometimes a function signature can tell you a lot about what a function is doing!).

So, as a consequence of this: should people work doing painful, manual work that might quickly go out of date? Or should they work on getting some of the basic infrastructure that would help with this in place?

1. Nix's documentation is clearly not great. However, I do not think it's bad, having actually stuck with using it. Can some of it be hard to read? Certainly, but 4 times out of 5 (roughly, guesstimating), it gets the point across, which is okay for documentation.

To be productive (relatively speaking), I had to follow a sequence like this:

• learn how to bookmark search engines so that I can query directly from my URL bar (https://support.mozilla.org/en-US/questions/1284520) (this isn't well documented for a lot of browsers either)
• bookmark Nixpkgs manual, NixOS manual, Nix Reference Manual (search engine bookmarkable), Nix.dev (in order to make up for the fact that there is no central repo
• bookmark (as search engines) search.nixos.org/packages? and search.nixos.org/options?
• bookmark (as search engines) GitHub queries lang:nix org:nixos <...> and lang:sh org:nixos <...> and finally (lang:nix) AND NOT ("home" OR "home-manager" <...>) -- because yes, reading the source code is unavoidable. But it's doable. It's okay. And more often than not, you'll be surprised by how well documented it is (which also should lead one to wonder: why is it hard to automate sharing of documentation between primary nix docs and the source code? see point 4 above)

That's enough to cover 80% of my needs. The remainder: I have to ask others for pointers about, and/or searching for PRs in flight for nix docs, and/or I have just discovered something undocumented.

Still though, this is 4/5. Not great, but not terrible.

As an illustration of the "noise in the channel" issue are you aware of:

• nix.dev? If so, when did you become aware of it? Was it one of the earliest/first resources you became familiar with? (For me, it was most certainly not, although today I see that it is linked under "first steps with Nix"...)
• Are you familiar with high-level conceptual articles like Taming Unix With Nix? If not, why not? Why don't they show up much, much higher on search engines? Why aren't they thrown around freely on HN?
• Are you familiar with the fact that the "Unofficial NixOS Wiki" is not well maintained, and contains lots of extremely low quality information?
• Are you familiar with the fact that the Nix Pills are currently not in a great shape, especially for beginners, despite them being advertised on nixos.org's learn page?

In reply to @qyriad:matrix.org
I can't speak for Chris McDonough, but I can't imagine this conversation inspires much faith in this Nix community's friendliness.

Chris McDonough's approach to how that conversation went was jarring for me, because I could not understand how they went from "no?", to my response with "precisely." to "<threat>" (this is how I perceived it). First off, I'm not a part of the Nix doc community, and am basically a random internet person. There are no special tags associated with my username. Why should my actions (and I am sorry, but I am not a trained diplomat, and I have struggles of my own that do not make it easy for me to do well socially!) be responsible for whether they participate in the community?

Furthermore, why not just ask me for clarification on what I am trying to communicate so that I feel welcome enough to lay them out? It was already a work-in-progress struggle to lay out the information in a non-wall-of-text-format (ultimately, I failed entirely). It took me a long time to write out the wall-of-text you do see above. That's a non-trivial time commitment, and it's worse when one spends that time, but it turns out that the wall-of-text itself is seen as unwelcome.

I also believe that asymmetric's response to the situation assumes that my original "no." was written with aggressive hostility, and helps frame my action as such immediately placating Chris McDonough and asking them to share their frustrations in private. As much as Chris McDonough is a contributor, so am I. As much as they are human, so am I. So if there there was a situation to be resolved, it involved both Chris and myself, rather than only Chris in private. Most importantly, if there was an issue, it involved understanding on both my part and Chris'.

I will openly accept that I made a mistake today, and I will take responsibility for it, including if moderators deem it necessary, by not participating here further. I will not accept however---and I firmly draw a line there---that I am unfriendly, aggressive or (and most importantly) unkind.

In reply to @qyriad:matrix.org
I can't speak for Chris McDonough, but I can't imagine this conversation inspires much faith in this Nix community's friendliness.

Chris McDonough's approach to how that conversation went was jarring for me, because I could not understand how they went from "no?", to my response with "precisely." to "<threat>" (this is how I perceived it). First off, I'm not a part of the Nix doc community, and am basically a random internet person. There are no special tags associated with my username. Why should my actions (and I am sorry, but I am not a trained diplomat, and I have struggles of my own that do not make it easy for me to do well socially!) be responsible for whether they participate in the community?

Furthermore, why not just ask me for clarification on what I am trying to communicate so that I feel welcome enough to lay them out? It was already a work-in-progress struggle to lay out the information in a non-wall-of-text-format (ultimately, I failed entirely). It took me a long time to write out the wall-of-text you do see above. That's a non-trivial time commitment, and it's worse when one spends that time, but it turns out that the wall-of-text itself is seen as unwelcome.

I also believe that asymmetric's response to the situation assumes that my original "no." was written with aggressive hostility, and helps frame my action as such by immediately working to placate Chris McDonough and asking them to share their frustrations in private. As much as Chris McDonough is a contributor, so am I. As much as they are human, so am I. So if there there was a situation to be resolved, it involved both Chris and myself, rather than only Chris in private. Most importantly, if there was an issue, it involved understanding on both my part and Chris'.

I will openly accept that I made a mistake today, and I will take responsibility for it, including if moderators deem it necessary, by not participating here further. I will not accept however---and I firmly draw a line there---that I am unfriendly, aggressive or (and most importantly) unkind.

Chris McDonough's approach to how that conversation went was jarring for me, because I could not understand how they went from "no?", to my response with "precisely." to "<threat>" (this is how I perceived it). First off, I'm not a part of the Nix doc community, and am basically a random internet person. There are no special tags associated with my username. Why should my actions (and I am sorry, but I am not a trained diplomat, and I have struggles of my own that do not make it easy for me to do well socially!) be responsible for whether they participate in the community?

Furthermore, why not just ask me for clarification on what I am trying to communicate so that I feel welcome enough to lay them out? It was already a work-in-progress struggle to lay out the information in a non-wall-of-text-format (ultimately, I failed entirely). It took me a long time to write out the wall-of-text you do see above. That's a non-trivial time commitment, and it's worse when one spends that time, but it turns out that the wall-of-text itself is seen as unwelcome.

I also believe that asymmetric's response to the situation assumes that my original "no." was written with aggressive hostility, and helps frame my action as such by immediately working to placate Chris McDonough and asking them to share their frustrations in private. As much as Chris McDonough is a contributor, so am I. As much as they are human, so am I. So if there there was a situation to be resolved, it involved both Chris and myself, rather than only Chris in private. Most importantly, if there was an issue, it involved understanding on both my part and Chris'.

I will openly accept that I made a mistake today, and I will take responsibility for it, including if moderators deem it necessary, by not participating here further. I will not accept however---and I firmly draw a line there---that I am unfriendly, aggressive or (and most importantly) unkind.

(and also, Qyriad)

I would have preferred it if you read my response with no hostility, because there frankly wasn't any. There was however, a degree of frustration as I thought your messages were quite hostile, and I struggled to respond cogently to them on my first try (I did not want to produce a wall-of-text, something I fall into easily).

As for why I thought your comments were hostile: they seemed entirely out of the blue. I scrolled up to try and find the context but could not find any; if I missed it please link me to it. Anyway, given this lack of context: I was not sure what these messages communicate apart from insinuating that those working on the docs think the docs are close to being done and/or that they aren't working hard enough? Rather hostile, yes?

So take my "no." for what it was, if you can (though I appreciate that this is likely not possible given how the situation evolved): a note of disagreement. Frustrated disagreement yes, but not hostile disagreement. Certainly no more hostile than your own message.

As for why I disagree: well, I am still not clear if you want to know. I am also not clear on how to not make it a wall of text. I am going to risk trying to put together something regardless. I hope again (though I appreciate that this is likely not possible) that you'll put some effort into reading what I'm sharing, instead of dismissing it outright as a "wall of text".

I decided to start contributing to Nix docs a few weeks ago, by doing light review work. I also really wanted to contribute to a working Wiki, and therefore was interested in getting Wiki 2.0 rolling. On the PR review front, infinisil's PR on File Sets grabbed my attention. I could not understand their answer, and found it frustrating, which lead me to put down this wall-of-text.

I am glad that proofconstruction wrote me a very detailed response, and I appreciate that they put in some effort to take me sincerely, even though it was hard and their frustration bled through. They made their doubt of my sincerity clear, and I made my own unhappiness with their doubt clear. Regardless, we gave each other the space to speak, and reached a mutual understanding, as you can see.

Far more important however, is what proofconstruction shares. Please read that, even if you cannot summon the motivation to read what I wrote. I learned a lot from it. And it's an excellent introduction to what the actual issues are:

1. Lack of humanpower, and lack of resources to ask people to work on a non-volunteer basis.
2. Split of community, and therefore the above mentioned resources, due to flakes, and how flakes are being conveyed/pushed.
3. Noise in the communication "channel": there is a lot* of misleading and/or poor quality content around Nix. Part of this may be put down to the way search engines work today, part due to how people are pushed to advertise themselves with blog posts, or where current trends in fashion are. Part of it is also due to the tragedy of the wiki which people are working hard to revive.

But barring all that, a non-trivial part of it is also due to politics. Nix is being advertised in ways that are unfair to those doing the actual work in the trenches.

Frankly, the learning journey becomes much easier if a beginner (speaking also as a fellow beginner!):

• drops home-manager: home-manager is not great for a variety of reasons, but a crucial one is that it uses concepts and terminology that are superficially similar to NixOS, but only superficially. This forces a beginner to have to learn two models, even though they think they are learning one model, and its frustrating when that knowledge isn't cross-applicable.
• drops flakes, flake-utils, etc. (and were instead exposed to niv or npins)

Later, once you're more familiar with Nix, you can go back to playing with those (if you still feel the need). But already, by implementing the aboeve two points, the documentation situation for a beginner has improved by cutting down on what they are required to take in at one go.

1. In order to document something, it is also necessary that the thing in question is documentable. Nix is in such a position (due to lack of resources, and humanpower, but also choices on the part of leadership) that it is not easy to document for fairly simple reasons such as: lack of typing. Type systems (amongst other things) are very helpful for auto-generation of documentation, and having "self-documenting" code (e.g. sometimes a function signature can tell you a lot about what a function is doing!).

So, as a consequence of this: should people work doing painful, manual work that might quickly go out of date? Or should they work on getting some of the basic infrastructure that would help with this in place?

1. Nix's documentation is clearly not great. However, I do not think it's bad, having actually stuck with using it. Can some of it be hard to read? Certainly, but 4 times out of 5 (roughly, guesstimating), it gets the point across, which is okay for documentation.

To be productive (relatively speaking), I had to follow a sequence like this:

• learn how to bookmark search engines so that I can query directly from my URL bar (https://support.mozilla.org/en-US/questions/1284520) (this isn't well documented for a lot of browsers either)
• bookmark Nixpkgs manual, NixOS manual, Nix Reference Manual (search engine bookmarkable), Nix.dev (in order to make up for the fact that there is no central search engine)
• bookmark (as search engines) search.nixos.org/packages? and search.nixos.org/options?
• bookmark (as search engines) GitHub queries lang:nix org:nixos <...> and lang:sh org:nixos <...> and finally (lang:nix) AND NOT ("home" OR "home-manager" <...>) -- because yes, reading the source code is unavoidable. But it's doable. It's okay. And more often than not, you'll be surprised by how well documented it is (which also should lead one to wonder: why is it hard to automate sharing of documentation between primary nix docs and the source code? see point 4 above)

That's enough to cover 80% of my needs. The remainder: I have to ask others for pointers about, and/or searching for PRs in flight for nix docs, and/or I have just discovered something undocumented.

Still though, this is 4/5. Not great, but not terrible.

As an illustration of the "noise in the channel" issue are you aware of:

• nix.dev? If so, when did you become aware of it? Was it one of the earliest/first resources you became familiar with? (For me, it was most certainly not, although today I see that it is linked under "first steps with Nix"...)
• Are you familiar with high-level conceptual articles like Taming Unix With Nix? If not, why not? Why don't they show up much, much higher on search engines? Why aren't they thrown around freely on HN?
• Are you familiar with the fact that the "Unofficial NixOS Wiki" is not well maintained, and contains lots of extremely low quality information?
• Are you familiar with the fact that the Nix Pills are currently not in a great shape, especially for beginners, despite them being advertised on nixos.org's learn page?