(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?

(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 on, 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?

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 unwelcoming.

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 unwelcoming.

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 required understanding on both our parts to resolve.

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 @9999years:matrix.org
yeah i mean, this is one of the issues with nix's docs -- nixpkgs and nix are deeply intertwined, but they can't be versioned together, even trivial stuff like lib

9999years Qyriad yes, Nix and Nixpkgs are entangled, and many new users aren’t even aware these are separate things because they come to NixOS and often seem to think it’s that one big thing.

But I maintain that strict separation of documentation for each component is not the problem, but one of the solutions. It’s been the way you’re proposing in the past (and still is in some places, especially at the Nixpkgs/NixOS boundary), and it made things worse.

There is a conceptually straightforward answer to this, which were slowly pursuing: have focused reference documentation for each component (the manuals) that is agnostic to how it’s used downstream, and an overview of how to navigate (tutorials), use (guides/recipes), understand (explanations) the overall system on nix.dev. I think having a wiki as a dump for scattered notes would be a good complement to that, because the effort to maintain curated materials with stronger reliability guarantees is quite high.

In reply to @9999years:matrix.org
this is the sort of connective tissue that's missing -- all the information is there, but users have a hard time finding it, and part of the reason for that is there's so many places to look for any given piece of information

In 2022 I started with exactly that assessment (which I still share) and with Eelco’s blessing and Tweag’s funding started this: https://github.com/nixos/nix-book

It turned out not to be that simple at all. The ecosystem is too large, the spectrum of use cases too wide, and the details too messed up to just sit down and vomit out how to use it properly and then wait for others to fix the typos. In fact, there have been multiple attempts by different people: https://github.com/NixOS/nix.dev/issues/454

Apart from the initial literature survey, I ran a a small usability study: https://discourse.nixos.org/t/usability-studies/21404 and evaluated the community polls: https://discourse.nixos.org/t/2022-nix-survey-results/18983

When the documentation team was founded the current strategy evolved based on the following considerations:

• nix.dev existed and was the highest quality overview resource out there, the Wiki existed and had the broadest coverage with varying quality - we shouldn’t start from scratch, also for discoverability purposes, so the book idea was dropped in favor of eventually developing nix.dev into that book eventually, incorporating useful bits from the wiki
• the system surface was enormous and messy, so improving everything at once under a somewhat consistent paradigm was (and still is) impossible. We had to focus on a meaningful and most impactful subset
• some things have to be figured out how to even use properly, or even fixed in the code before one can write any documentation. And before writing a tutorial or guide, one needs proper reference documentation. Often that’s lacking, we’ve experienced that for every piece we worked on.
• the most important part for user retention is onboarding and contributing. The only thing usable in isolation is Nix itself.

So this is what we did and are still doing, and we’re quite far advanced with improving the documentation relevant for the first couple of weeks using vanilla Nix. I don’t have the numbers to prove it, but from anecdata and heuristics about the types of questions asked on Discourse, I think we managed to substantially reduce the average initial onboarding time and fraction of people who give up before concluding that.

And even that took what feels like forever, because we ran into many obstacles that relate to governance issues. The first impressions are highly exposed material and so I have to get change proposals past people who have authority over the pieces in question. That’s another reason why we focus on nix.dev more than anything else: the documentation team has free reign over it (within the constraints of not breaking things that already worked for people).

Which means that still, NixOS and Nixpkgs documentation have barely improved in the meantime. We here know all the issues with it, but dealing with them takes time that’s taken away from the original mission. We’re trying to balance that, because not supporting attempts at contributions is of course frustrating for everyone.

What we really need are dedicated maintainers for the various sections of the Nixpkgs manual, all of the NixOS manual, and ideally editors for the (upcoming new) Wiki. This stuff is up for grabs, and I’d definitely recommend org owners to hand out commit bits to anyone who demonstrates they understand and subscribe to the general direction we’re taking. So far no one stepped up, and those who considered, reconsidered again after dipping their toes into the intricacies of the stuff actively being worked on.

We first have to get the basics right before piling stuff on top. There’s already way too much stuff piled up, and the basics are still not in a great shape.

In reply to @infinisil:matrix.org
Needs a unified docs building infrastructure though

In reply to @9999years:matrix.org
those PRs look great! what's blocking them from being merged?

In reply to @asymmetric:matrix.dapp.org.uk
btw, we have ~60 prs in nixpkgs that are about documentation, but have no 6.topic: documentation label, including some by mebers of this team. i think it would be helpful to ensure that label is added, so we can triage them instead of letting them rot.

hmm, the label description says "Meta-discussion about documentation and its workflow", so maybe i'm wrong that it should be applied to those prs?

should documentation PRs have that label, or not?

In reply to @infinisil:matrix.org
asymmetric: Sounds like the label description should be updated then :)

In reply to @infinisil:matrix.org
I feel like the content vs infra distinction sounds better

In reply to @infinisil:matrix.org
I feel like the content vs infra distinction sounds better

Just went through a rabbithole when creating a PR, and have a few questions that I think would be better asked here rather than spending even more time trying to dig things:

1. Does anyone know why a bunch of places in our docs use the shellSession/ShellSession info on code blocks? https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20shellsession&type=code
   From my investigation, it seems to be ignored by the highlighting library we use in the manuals
2. A look into the highlighting library used in the manuals makes me believe that the unstable manuals haven't been updated in nixos.org for at least 2 months (library was updated from v9 to v11 ~2mo ago, but the version used in nixos.org is still v9). I can't spend more time today looking into this, but I think this isn't normal. Did something break in the manual -> nixos.org pipeline?