fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

1. the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

1. (if we ignore 1, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

1. (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?

• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?

• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).

• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they are actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

1. the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

1. (if we ignore 1, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

1. (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?
• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?
• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).
• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

fricklerhandwerk:

I recently asked someone writing for the documentation team why they were mentioning niv (and not flakes), and related: why they were mentioning nix-build and not nix build in a tutorial that is ultimately going to live on nix.dev. They helpfully answered with the following: https://github.com/NixOS/nix.dev/pull/802#discussion_r1398526182

I would like to ask about the conclusions reached by the documentation team, as explained in the above posts. It is difficult for me (currently) to believe they are actual facts rather than convenient fictions. Obviously, what I think does not matter, but I suppose perhaps that this gives me the room to speak freely.

In the explanation for why the documentation team is operating based on the currently agreed upon rules, the following underlying points are especially difficult for me to understand:

ONE the belief that stabilization is a fixed goal, with associated objective metrics that let us determine how close we are to stabilization, rather than "stabilization" being a concept motivated by aesthetics (for a small team/single person) or politics (for a larger team).

This seems to ignore:

• that documentation is a part of the process of the aesthetic/political requirements that allows judgements regarding what is stable vs unstable; (also, as a consequence, decisions made by documentation teams regarding what should be documented are political decisions too.)
• that documentation (or lack thereof) contributes to how easy it is to "stabilize" (or destabilize) a feature.
• that it is possible for a feature's opposition to constantly change the requirements of the "is stabilized" condition, so that the feature is effectively never stabilized;
• that it is possible for something to be "stable" only because it is no longer being maintained, or that there is an instability inherent in the process of maintenance and incremental improvement.
• that we have objective measurements which allow us to conclusively determine that some aspects of Nix are stable, while others are not. Suppose we could come up with such a metric: then what goes into such a metric? Is it merely a matter of how frequently the function signatures change?

TWO (if we ignore ONE, and agree that stabilization is more objective than mere politics/aesthetics) the belief that if something is stabilized, it is easier to document; and conversely, the belief that if something is unstable, then it is harder to document

This seems to ignore that:

• something that is "stable" may be so convoluted, that it is difficult to document; conversely that something that is "unstable" may be much simpler conceptually.
• that documentation as en effort, is not separate from development, as an effort. It is possible, and also perhaps desirable, to ask that change authors accompany their work with some degree of documentation by default.

THREE (again, if we agree to ignore 1) the belief that if something is stabilized, it is more relevant to document (therefore, should be prioritized in resource limited contexts)

This seems to ignore:

• there might be more important tasks than documenting what is stable:

For example, imagine we have a situation where the documentation team is resource-limited, and knowledge of the system tends to live mostly in the minds/actions of people, rather than being codified centrally.

Then it might make sense to capture as much of that informal information as possible as preparation for more targeted documentation efforts. The easiest way to do this is to open up an official wiki that is easy to contribute to (easy to write articles for). People can participate with ease both with respect to the presentation quality of what they contribute, and if they do not want to contribute, they can merely help improve the presentation quality. It is also easier to record disagreements on a particular area (see how the Arch Wiki handles this by showing small notification markers over controversial sections which give a quick summary of the controversy, and a link to where the discussion is being held).

A resource limited documentation team can also then benefit from the Wiki by lifting those parts which can be moulded/sharpened into fully official formal documentation.

Why has it been so hard to get Mic92's Wiki revival hosted?

• that it is important to consider that part of the purpose of documentation is to help onboard newcomers. So it is important to consider what they are being onboarded onto. Is it what is currently stable? Or what is soon to be stabilized? The answer to this question is more important in determining what ought to be documented first, instead of "what is stable right now"?
• that part of the purpose of documentation is to help build up the community, therefore if it contributes to areas of confusion by further confusing matters, then it might be anti-productive (which is worse than being non-productive)?
• that a resource constrained documentation ought to also think about how existing pieces of disparate information can be re-moulded into material of higher quality, rather than only create documentation de novo. As a first step, collecting a library of links to useful documentation that are vetted by the documentation for quality would be helpful not only in providing information, but also providing a list of resources that documentation team members have the permission to re-mould into official documentation (with the authors' permission; if an author chooses not to give permission, their work need not be included).
• that a resource constrained documentation team ought to figure out how it can be less resource constrained (i.e. have more participants), and prioritize activities which lead to natural growth of the team, rather than prioritize based on stable/unstable?

Supposing this is sincere, some answers and responses to the above, in no particular order, with the usual caveats that this is my opinion/perspective and I don’t speak for others, and also that I am both tired (from work unrelated to nix) and frustrated (from the same) so my tone here is less pleasant than I’d normally want to put in public channels:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.
• you are free to contribute to the unofficial wiki as you like
• lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.
• Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.
• you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!
• I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
• everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

bzm3r: Also some unorganized points:

• Instead of diverting our attention to the Flakes discussion again, I'd much rather just have reviews for the actual content of https://github.com/NixOS/nix.dev/pull/802 :)
• Personally, I think Flakes are really poorly designed, and if they get marked as stable as is, I might just fork Nix or leave the community
• Nix is stable when the Nix team calls it stable. In practice this means being able to rely on it for decades to come

In reply to @proofconstruction:matrix.org

Supposing this is sincere, some answers and responses to the above, in no particular order, with the usual caveats that this is my opinion/perspective and I don’t speak for others, and also that I am both tired (from work unrelated to nix) and frustrated (from the same) so my tone here is less pleasant than I’d normally want to put in public channels:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.
• you are free to contribute to the unofficial wiki as you like
• lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.
• Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.
• you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!
• I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
• everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

First off, I don't think you know what is going on in my life either. Except, I didn't advertise them, nor did I use it as an excuse to be cruel. So to hear things like "supposing this is sincere..." and then to be told things like:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.

...well, let's just leave it at: "I am glad you don't know what's going on in my life". I was about to type out something like this:

What is vague about the notion of productive like: how can the documentation team help people learn Nix effectively? 

I'm a newcomer. It has been a really weird challenge to navigate learning Nix. I'm trying to think through why that is, based on my recent experience, and was trying to put in effort into contributing to Nix docs. I tried to help review a recent PR, and had some questions based on that. The answer to that question didn't entirely make sense to me, and I tried to be careful by writing out why I felt it didn't make sense to me, rather than merely say "that doesn't make sense". 
 
What is so *insincere* about that?

...but I don't think it would make a difference to say that, (trying to put on a positive hat) because you are not responding to me, you're responding to an amalgamation of your past experiences ("...much digital ink has been spilled already").

you are free to contribute to the unofficial wiki as you like

This is something I have explored, and my experience there suggests that you're saying I should contribute there not because it's a viable option that would be meaningful, but probably because:

• (more positively) you have not used it and don't know the story around it currently, or
• (more negatively) you are politely telling me to "fudge off".

lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.

I think you misread which wiki it is that I suggest a documentation team might eventually lift content from (it is not the unofficial one)...and the rest is irrelevant given that.

Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.

The goal is not to have users for the sake of having contribution. The goal is to allow newcomers to learn this tool, so that they too may improve their life through its use. Also, we do not need 99/100 new users contributing back; having 1/10.000 new users doing so is good enough...it's how open source works...

So, the meat of your point here is that the goal of teaching newcomers is an anti-goal for you (and apparently some others here too, e.g. maybe those who reacted with a ❤️ to your message). The Nix Documentation team should be explicit about this so that unwitting people like me don't mistake its goals. If I had known that, a lot of what I did write, I would have known not to write.

you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!

You're definitely helping me feel quite welcome! Also, just a few days ago, I explicitly posted here asking if anyone wanted an extra pair of hands/eyes to help write/review anything. I didn't receive a response. So...I engaged on my own...

I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

I'm not sure why you put these two points last, and I am also not sure I understand why you bothered to write anything else above it (apart from "onboarding newcomers is an anti-goal"). These two points alone are enough to answer all my questions.

I didn't even have a solid opinion on Nix flakes. I only know about them (and therefore used them) because of the Nix resources I ran into which were most approachable. (In particular: https://fasterthanli.me/series/building-a-rust-service-with-nix/part-10)

I was just confused about "why the thing people seem to be using the most" is not the thing we are also documenting.

For me at least, flakes are no more confusing than any other part of Nix, and I think most of the confusion around flakes is the same as for any other part of Nix: 1) lack of cohesion around how something ought to be done (there always seem to be a bunch of different ways) and 2) lack of discoverability through reading code alone, because of the lack of a typing system, and the existence of syntactic sugar/"magic features" that hide important connecting logic (e.g. how a certain variable is passed between certain contexts).

I'm totally willing to believe that flakes are more confusing, and are horrible. I just don't have enough experience, and in particular: I happened to (by chance) not run into high quality tutorials that don't involve flakes. I also ran into discussion (on news.ycombinator.com) about how flakes make Nix much easier to work with...

So, uh, yeah...

I guess I have to ask: you haven't made it clear how common the anti-flake/anti-newcomer view is. Is this official policy for the Nix project as a whole?

• If yes, why is it just not written clearly, so that simpletons like me would have known not to bother with reading about flakes and instead focus on the non-flakes way? (And also to not bother trying to write about how the docs aren't currently working well. Well, yeah, they aren't, because...their goal is not to help me; and that's okay!)

• If not, then I wonder: are you a part of the Nix docs team? If so, why are you engaging in an official team that you are anti-oriented with? Wouldn't it be healthier for you, and for the Nix project, if you put your efforts elsewhere (e.g. writing blog posts/making a No-Flakes-Here Nix Wiki/forking Nix)?

In reply to @infinisil:matrix.org

bzm3r: Also some unorganized points:

• Instead of diverting our attention to the Flakes discussion again, I'd much rather just have reviews for the actual content of https://github.com/NixOS/nix.dev/pull/802 :)
• Personally, I think Flakes are really poorly designed, and if they get marked as stable as is, I might just fork Nix or leave the community
• Nix is stable when the Nix team calls it stable. In practice this means being able to rely on it for decades to come

Thanks infinisil! I'm still glad that you wrote your tutorial, and that I reviewed it. Also, I'll re-iterate what I wrote in the my post-review comment on GitHub:

Thank you for this! I love reading new tutorials. I have a couple of suggestions, but I'm not really sure what the nix.dev policy is around flakes/"experimental commands", so I might be off-base.

I do wish you had answered my question on GitHub with what you wrote here (then I wouldn't have been confused enough to write what I did). In particular:

Personally, I think Flakes are really poorly designed, and if they get marked as stable as is, I might just fork Nix or leave the community

That's really good to know up-front, because that makes a lot more sense to me around why flakes aren't mentioned in the tutorial, than the rest of the things you told me! (Particularly around the "stabilization" of flakes being the concern of the docs team.)

Nix is stable when the Nix team calls it stable. In practice this means being able to rely on it for decades to come

Fair enough. Again, this is much clearer to me as an answer than "Nix stable is what we're focusing on because flakes are unstable". Like, that suggests that stability is somehow a goal that has to be reached before documentation is meaningful, while what you've written here provides a different picture.

In reply to @proofconstruction:matrix.org

Supposing this is sincere, some answers and responses to the above, in no particular order, with the usual caveats that this is my opinion/perspective and I don’t speak for others, and also that I am both tired (from work unrelated to nix) and frustrated (from the same) so my tone here is less pleasant than I’d normally want to put in public channels:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.
• you are free to contribute to the unofficial wiki as you like
• lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.
• Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.
• you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!
• I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
• everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

First off, I don't think you know what is going on in my life either. I didn't advertise my challenges, nor did I use it as an excuse to be cruel. So to hear things like "supposing this is sincere..." and then to be told things like:

• pursuing some vague notion of “productivity” for its own sake doesn’t help anyone, and is typically harmful.

...well, let's just leave it at: "I am glad you don't know what's going on in my life". I was about to type out something like this:

What is vague about the notion of productive like: how can the documentation team help people learn Nix effectively? 

I'm a newcomer. It has been a really weird challenge to navigate learning Nix. I'm trying to think through why that is, based on my recent experience, and was trying to put in effort into contributing to Nix docs. I tried to help review a recent PR, and had some questions based on that. The answer to that question didn't entirely make sense to me, and I tried to be careful by writing out why I felt it didn't make sense to me, rather than merely say "that doesn't make sense". 
 
What is so *insincere* about that?

...but I don't think it would make a difference to say that, (trying to put on a positive hat) because you are not responding to me, you're responding to an amalgamation of your past experiences ("...much digital ink has been spilled already").

you are free to contribute to the unofficial wiki as you like

This is something I have explored, and my experience there suggests that you're saying I should contribute there not because it's a viable option that would be meaningful, but probably because:

• (more positively) you have not used it and don't know the story around it currently, or
• (more negatively) you are politely telling me to "fudge off".

lifting useful content from the wiki for import into the official docs is a project some of us are interested in taking on at some point, but the team is usually only 3 or 4 part time and inconsistently-available contributors in any given week, with most of these volunteering. Resource constraints are severe.

I think you misread which wiki it is that I suggest a documentation team might eventually lift content from (it is not the unofficial one)...and the rest is irrelevant given that.

Onboarding new users has been a goal by both this team and the broader project/ecosystem, but is considered by some (myself among them)to be an anti-goal: users do not necessarily contribute, which is what the project (not just docs, everything) actually needs to flourish.

The goal is not to have users for the sake of having contribution. The goal is to allow newcomers to learn this tool, so that they too may improve their life through its use. Also, we do not need 99/100 new users contributing back; having 1/10.000 new users doing so is good enough...it's how open source works...

So, the meat of your point here is that the goal of teaching newcomers is an anti-goal for you (and apparently some others here too, e.g. maybe those who reacted with a ❤️ to your message). The Nix Documentation team should be explicit about this so that unwitting people like me don't mistake its goals. If I had known that, a lot of what I did write, I would have known not to write.

you are welcome to “grab a shovel”, as some of us say, and help with the documentation effort (or even better, the flakes stabilization/detangling effort). Meeting times are available on the calendar. Join us!

You're definitely helping me feel quite welcome! Also, just a few days ago, I explicitly posted here asking if anyone wanted an extra pair of hands/eyes to help write/review anything. I didn't receive a response. So...I engaged on my own...

I say “detangling” above because flakes are so convoluted as to be difficult to document, and not for lack of trying; see any number of blog posts by various people on this topic, and the fact that we are still having this discussion
everything is political and many decisions are absolutely made based on aesthetic sensibilities. It is a fact that many involved in this work just don’t like the miserable little pile of features we call “flakes”today, and believe those pieces should be included in nix in a different form. Much digital ink has been spilled on this already

I'm not sure why you put these two points last, and I am also not sure I understand why you bothered to write anything else above it (apart from "onboarding newcomers is an anti-goal"). These two points alone are enough to answer all my questions.

I didn't even have a solid opinion on Nix flakes. I only know about them (and therefore used them) because of the Nix resources I ran into which were most approachable. (In particular: https://fasterthanli.me/series/building-a-rust-service-with-nix/part-10)

I was just confused about "why the thing people seem to be using the most" is not the thing we are also documenting.

For me at least, flakes are no more confusing than any other part of Nix, and I think most of the confusion around flakes is the same as for any other part of Nix: 1) lack of cohesion around how something ought to be done (there always seem to be a bunch of different ways) and 2) lack of discoverability through reading code alone, because of the lack of a typing system, and the existence of syntactic sugar/"magic features" that hide important connecting logic (e.g. how a certain variable is passed between certain contexts).

I'm totally willing to believe that flakes are more confusing, and are horrible. I just don't have enough experience, and in particular: I happened to (by chance) not run into high quality tutorials that don't involve flakes. I also ran into discussion (on news.ycombinator.com) about how flakes make Nix much easier to work with...

So, uh, yeah...

I guess I have to ask: you haven't made it clear how common the anti-flake/anti-newcomer view is. Is this official policy for the Nix project as a whole?

• If yes, why is it just not written clearly, so that simpletons like me would have known not to bother with reading about flakes and instead focus on the non-flakes way? (And also to not bother trying to write about how the docs aren't currently working well. Well, yeah, they aren't, because...their goal is not to help me; and that's okay!)
• If not, then I wonder: are you a part of the Nix docs team? If so, why are you engaging in an official team that you are anti-oriented with? Wouldn't it be healthier for you, and for the Nix project, if you put your efforts elsewhere (e.g. writing blog posts/making a No-Flakes-Here Nix Wiki/forking Nix)?

... notion of productive like: how can the documentation team help people learn Nix effectively?

This is indeed a goal, just not the only goal, and we're stretched so thin as to have to pick just one.

... telling me to "fudge off"

Not at all, in fact I welcome any new energy to this corner of the project -- I would be thrilled for you to join and help us! Just, the unofficial wiki is precisely the place where one can make wiki-style contributions. Now speaking for others: we see no reason to duplicate that effort, and instead focus on producing what we believe to be higher quality (in particular, more narratively-consistent) materials, like today's nix.dev.

The goal is not to have users for the sake of having contribution. The goal is to allow newcomers to learn this tool, so that they too may improve their life through its use.

The trouble here is that non-contributing users (I was one for my first ~6 years using Nix!) are usually not also non- consuming, in the sense of requiring additional resources from teams that already don't have them. Hence the docs effort: well-designed (in particular, narratively-consistent) documentation can be a tremendous force multiplier for teaching, but the Nix ecosystem broadly does not have well-designed docs; famously so! We (again now speaking for others) do in fact want to improve lives by getting more people into effective Nix use, but this is in tension with Nix not actually being a very good tool: its edges are very sharp, and many cut themselves and wind up here looking for aid. That Nix works at all is very nearly a miracle. A chainsaw is useful too, but I don't want to leave one lying around for others to hurt themselves or others with, and right now the hard decision for many of us is between building a sheath for the saw and writing an instruction manual for it. Neither of these are reasonable approaches to the problem of new people running into trouble after picking up the cool saw.

Also, we do not need 99/100 new users contributing back; having 1/10.000 new users doing so is good enough

We already have 1/10000 users contributing; the entire project ecosystem is sustained by the heroic efforts of fewer than 100 people.

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

... a few days ago, I explicitly posted here asking if anyone wanted an extra pair of hands/eyes to help write/review anything. I didn't receive a response

Sincerely: my apologies for this. We are all tremendously busy, and frequently are not able to appropriately reply. We will always welcome extra help - please join the next team meeting at 15:00 UTC!

I was just confused about "why the thing people seem to be using the most" is not the thing we are also documenting.

Indeed this is a giant problem: the thing people are using the most is also the most broken. This is not really even my opinion, but a matter of technical fact. I even use flakes for my own system configurations, but this is still the case largely because I, like so many, adopted that workflow without any awareness of the problems lurking beneath the surface (also at the surface; flake.nix is not even a valid Nix file!)

For me at least, flakes are no more confusing than any other part of Nix

For me too! But this is really because the whole ecosystem generally has poor documentation.

... lack of discoverability through reading code alone, ... lack of a typing system, ... "magic features" that hide important connecting logic

Oh yes. You cannot possibly imagine how strongly I agree here. I think we'll be friends after all :)

... discussion (on news.ycombinator.com) about how flakes make Nix much easier to work with

Some parts, certainly! Flakes have a lot of good ideas, just sort of all crammed into the same space, unfortunately. They deserve much more love from dedicated contributors who can separate out the various concerns and make them into proper Nix features, rather than an unspecified informal soft fork living in the same codebase, like a sad vampire.

... put your efforts elsewhere (e.g. writing blog posts

I've deleted mine, actually. There are too many as it is.

... making a No-Flakes-Here Nix Wiki

nix.dev is almost this, but is really more a No-Flakes- Yet un-Wiki. This isn't a holy war; in fact you will likely find that some of the biggest detractors of flakes are also some of the most enthusiastic about the utility they (could, and were intended to) bring. We all want reproducibility and easy extension of Nix magic into new domains!

... forking Nix

I prefer to avoid making unilateral decisions like this (for example, by spending months moving PRs with the team instead of firing off blog posts solo every morning).

In reply to @proofconstruction:matrix.org

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

I agree that this is super important too, because it was definitely a struggle for me to figure this out. I would be very happy to have a look at PR 696 and leave a review.

I also benefited from using nix-init (just to check out what it generates in order to help me learn Nix packaging patterns, or to use what it generates as a template for further extension)...and was quite disappointed I discovered that rather indirectly (someone was nice enough to tell me about it here when I was struggling to package something).

So, when I see that mentioned by zmitchell as something you might consider inserting in #696, I heartily agree!

In reply to @proofconstruction:matrix.org

... the goal of teaching newcomers is an anti-goal for you

Teaching newcomers to contribute is my goal, at this point. You can convince yourself of this by checking my more recent (albeit some months ago due to significant life changes) contributions, particularly in the "packaging existing software" tutorial and the draft Nixpkgs contribution tutorial that follows (PR 696 could use your help!).

I agree that this is super important too, because it was definitely a struggle for me to figure this out. I would be very happy to have a look at PR 696 and leave a review (edit: I did just finish doing that!)

I also benefited from using nix-init (just to check out what it generates in order to help me learn Nix packaging patterns, or to use what it generates as a template for further extension)...and was quite disappointed I discovered that rather indirectly (someone was nice enough to tell me about it here when I was struggling to package something).

So, when I see that mentioned by zmitchell as something you might consider inserting in #696, I heartily agree!

In reply to @proofconstruction:matrix.org

... telling me to "fudge off"

Not at all, in fact I welcome any new energy to this corner of the project -- I would be thrilled for you to join and help us! Just, the unofficial wiki is precisely the place where one can make wiki-style contributions. Now speaking for others: we see no reason to duplicate that effort, and instead focus on producing what we believe to be higher quality (in particular, more narratively-consistent) materials, like today's nix.dev.

I am inspired to suggest an alternative to the whole wiki thing, after reading PR#696.

I guess I'm wondering: why don't we just hit the accept button on the decent suggestions made by infinisil and zmitchell, and then just merge the darn thing? It's really good enough as is! It shouldn't have stayed as long as it has in PR review mode...and I think that's what I crave the most when I ask for a wiki.

I know how much my perfectionism gets in the way of getting something completed (or even started), and recently circumstances in life have forced me to accept that "it feels better to just not care"...surprisingly, this made me more productive, not less...

Wiki has a culture that enables that, but maybe it's a silly excuse to want to wait for a wiki to solve our problem there, when we could just....merge things faster 😅